Running/Testing

afb-sec-gate-oidc is an afb-binder-v4 extension and cannot work with afb-binder-v3.

Check with afb-binder --version that your version >= 4.0.0

Requirements

  • you should have a valid afb-binder > v4.0.0 installed.
  • you should write or copy a sample oidc-config.json

  • you should know the path to:

    • libafb-sec-gate-oidc-ext.so extension
    • fedid-binding.so binding
    • libfedid-types.so type converters
  • you need a test client
    • sec-gate-oidc basic HTML/JS testing pages.
    • sec-gate-webui for one-page HTML Angular

If you run redpesk or a SDK container, simply install the package with dnf install sec-gate-oidc

Quick test

start sec-gate-oidc samples

Use one of the default config templates to write your own one and start the binder with your own oidc-config.json

 # check with PAM login as fake IDP
 afb-binder --config=/my_config/oidc-local.json

Note: any test with an external authority requires a minimum level of remote configuration. Check specific IDPs requirement before trying oidc-oauth2.json samples.

Connect to HTML5 test page

Connect your browser to your sec-gate-oidc service with https://target:port to display corresponding HTML5 test page. When testing on your local machine redirect uri should look like https://localhost:1234 when running sgate on a target, then your should use https://target-ip-addr

  • Note:

    • HTTPS requires SSL certificates. Check $PROJECT/data/ssl/gen-cert.sh to generated self signed SSL certificates. For development only, you may also choose to remove SSL. To remove SSL simply set ‘HTTPS’:false within your oidc-config.json

    • Warning: most IDPs impose HTTPS connection when using anything different from localhost as redirect login URL.

Run a test from building tree

Create a custom config file from samples available at ‘../data/etc/oidc-*.json’. When config looks good try it with afb-binder –config.

Note that it is a good ‘best-practice’ to check your json config with ‘jq’ on equivalent tools before trying to use it.

    jq < ../data/etc/my-oidc-config.json
    afb-binder --config=../data/etc/my-oidc-config.json -v

Warning NFC USB reader (ACR122U) with pcscd

  • Do not forget to update NFC kernel module blacklist

    • sudo cp $SOURCES/libs/pcscd-client/test/nfc-blacklist.conf /etc/modprobe.d

    • rmmod nfc and dependencies (or reboot)

    • systemctl enable pcscd.service

Check with you USB reader is visible with

    ./build/package/bin/pcscd-client --list
    -- reader[?]=ACS ACR122U PICC Interface 01 00

set up your HTTPS/TLS environment

You need TLS certificate for your HTTPS connection. In development mode you may use $SGATE/data/ssl/gen-cert.sh to generate as many as you need.

Generated certificate should be declared with “https-cert” and “https-key” of afb-binder configuration.

  "https": true,
  "https-cert": "../data/ssl/devel-cert.pem",
  "https-key": "../data/ssl/devel-key.pem",
  "extension": "./package/lib/libafb-sec-gate-oidc-ext.so",

make visible your HTML pages/applications

Make visible your HTML/JS files from sgate in order to expose it to client browser. For test you probably want to run everything with relative path from afb-binder rootdir.

   "roothttp": ".",
   "rootdir":  "../data/htdocs",

Note: if your application requires some absolute path use alias to make visible external to rootdir file to client browser.

 "alias": [
    {"uid": "external-files", "url":"/browser-path", "path":"/path/on/disk" },
        ...
]

Create/import HTML login pages

sgate ships two sets of login pages.

  • Simple/HTML5: for developer to understand the protocols.
  • Angular/HTML5: for people who need a modern and production oriented HTML5/UI.

First one is ship within source code $SOURCES/data/htdocs, second is ship through an independent package named sec-gate-webui.

When installed your HTML pages should match with the global section of your configuration.

     "globals": {
          "login": "/sgate/basic/login.html",
          "register": "/sgate/basic/register.html",
          "fedlink": "/sgate/basic/fedlink.html",
          "error": "/sgate/basic/error.html",
      },

‘onepage’ HTML5 url style is supported and configured URLs may include ‘#’ and/or as many query list arguments as needed. The only constraint is that when using a query list configured URL should include a trailing ‘&’

     "globals": {
          "login": "/sgate/onepage/myapp#login?style='cool'&",
          "register": "/sgate/onepage/myapp#register?style='cool'&",
          "fedlink": "/sgate/onepage/myapp#fedlink?style='cool'&",
          "error": "/sgate/onepage/myapp#error?style='cool'&",
      },

WARNING: global section uses browser URL not disk path. If URL/fullpath do not match afb-binder rootdir/httproot you should use the alias section to create an adequate match.

"alias": [
    {"uid": "basic-html", "url":"/sgate/basic", "path":"idps/my-basic-html-pages" },
    {"uid": "smart-html", "url":"/sgate/onepage", "path":"idps/my-onepage-app" },
...
]

When correctly configured trying to access a protected resource, should redirect your browser to your login page. Either to select one IDP from a list, or directly to your IDP if you only use one.

Configure your IDP

This is the most tricky part as configuration is specific to every IDP. Nevertheless all IDPs share equivalent requirements to register a new application:

  • register as a developer, some like Google, Microsoft,… request a credit card, even if they promise that it is only to be sure that you are not a robot and that they will never use it.

  • register an application: most IDP will ask for: name, logo, …

  • register application login redirect uri. This is the uri where your browser is redirected after a successful authentication. Note that this uri does not need to be visible from the IDP, it only has to be visible from your browser. As a result https://localhost:1324 or https://my-board.local can be valid.

  • optionally they may ask a logout request. Note that contrarily to login uri the logout one should be directly accessible from the IDP. This is because logout is a back channel request that happens when user session terminates.

In order to test social authentication we recommend the 3 following authorities:

  • github: while not OpenID-connect but only oAuth2 compliant, Github remains very simple and flexible to use as identity authority. Furthermore as yourself and most of your developers bodies should already have an account it is a very simple option to share test/config with colleagues and friends.

  • phantauth: this is not a real identity authority but more a very friendly reference tool to test/debug applications. Phantauth does not require any registration. You may generate as many client-id as needed and login page only asks a login without password. Note that Phantauth allows to provision user or application directly via REST request which might be very useful when trying to build an automatic CI test scenario.

  • onlogin: this is a real identity provider that supports far more than openid. It’s developer account is simple to activate and the limitations are more than acceptable (3 applications and 25 users) which should be more than enough to start.

    see onelogin kick-start

They are many other openid-connect authorities that proposes free developer accounts. Unfortunately we did not find application registration as intuitive as on github or onelogin.

JWT