Registering an OIDC client

Version 3.1 by mmorgan on 2020/07/16 01:46

Creating your OpenID Connect client

The steps to create an OpenID Connect (OIDC) client are the following:

get an access token from the `developer` client
save your registration access token for further modifications of your client
use the token to call the create endpoint

Note that a Jupyter Notebook notebook is available in the Drive of this collab to help you create and modify your OIDC client. Its name is: Managing an OpenID Connect client.ipynb [add link]

Fetching your developer access token

Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.

This can be achieved with this sample shell script:

# Gather username and password from user
read -p 'Enter your username: ' clb_dev_username
read -s -p 'Enter your password: ' clb_dev_pwd

# Fetch the token
curl -X POST https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token \
-u developer: \
-d 'grant_type=password' \
--data-urlencode "username=${clb_dev_username}" \
--data-urlencode "password=${clb_dev_pwd}" |

# and pretty-print the JSON response
json_pp

# Erase the credentials from local variables
clb_dev_pwd=''; clb_dev_username=''

The response will be similar to:

{
   "access_token": "eyJhbGci...",
   "expires_in": 108000,
   "refresh_expires_in": 14400,
   "refresh_token": "eyJhbGci...",
   "token_type": "bearer",
   "not-before-policy": 1563261088,
   "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
   "scope": ""
}

Store a copy of the "access_token" value. You will need if for the next step.

Creating the client

You can now create clients by sending a JSON representation to a specific endpoint:

# Set your developer token
clb_dev_token="eyJhbGci..."

# Send the creation request
curl -X POST https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/ \
-H "Authorization: Bearer ${clb_dev_token}" \
-H 'Content-Type: application/json' \
-d '{
        "clientId": "my-awesome-client",
        "name": "My Awesome App",
        "description": "This describes what my app is for end users",
        "rootUrl": "https://root.url.of.my.app",
        "baseUrl": "/relative/path/to/its/frontpage.html",
        "redirectUris": [
            "/relative/redirect/path",
            "/these/can/use/wildcards/*"
        ],
        "webOrigins": ["+"],
        "bearerOnly": false,
        "consentRequired": true,
        "standardFlowEnabled": true,
        "implicitFlowEnabled": true,
        "directAccessGrantsEnabled": false,
        "attributes": {
            "contacts": "first.contact@example.com; second.contact@example.com"
        }
    }' |

# Pretty print the JSON response
json_pp;

In case of success, the endpoint will return its representation of your client:

{
  "defaultClientScopes" : [
     "web-origins",
     "roles"
   ],
  "redirectUris" : [
     "/relative/redirect/path",
     "/these/can/use/wildcards/*"
   ],
  "nodeReRegistrationTimeout" : -1,
  "rootUrl" : "https://root.url.of.my.app",
  "webOrigins" : [
     "+"
   ],
  "authenticationFlowBindingOverrides" : {},
  "baseUrl" : "/relative/path/to/its/frontpage.html",
  "description" : "This describes what my app is for end users",
  "notBefore" : 0,
  "frontchannelLogout" : false,
  "enabled" : true,
  "registrationAccessToken" : "eyJhbGciOi...",
  "consentRequired" : true,
  "fullScopeAllowed" : false,
  "clientAuthenticatorType" : "client-secret",
  "surrogateAuthRequired" : false,
  "directAccessGrantsEnabled" : false,
  "standardFlowEnabled" : true,
  "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
  "attributes" : {
     "contacts" : "first.contact@example.com; second.contact@example.com"
   },
  "name" : "My Awesome App",
  "secret" : "your-client-secret",
  "publicClient" : false,
  "clientId" : "my-awesome-client",
  "optionalClientScopes" : [],
  "implicitFlowEnabled" : true,
  "protocol" : "openid-connect",
  "bearerOnly" : false,
  "serviceAccountsEnabled" : false
}

Among all the attributes, you should securely save:

your client secret ("secret" attribute): it is needed by your application to authenticate to the IAM server when making back-end calls
your client registration access token ("registrationAccessToken"): you will need it to authenticate when modifying your client in the future

Modifying your client

Update your client with a PUT request:

# Set your registration token and client id
clb_reg_token="eyJhbGciOi..."
clb_client_id="my-awesome-client"

# Update the client. Note that the client ID appears both in the endpoint URL and in the body of the request.
curl -X PUT https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/${clb_client_id} \
-H "Authorization: Bearer ${clb_reg_token}" \
-H 'Content-Type: application/json' \
-d '{
        "clientId": "'${clb_client_id}'",
        "redirectUris": [
            "/relative/redirect/path",
            "/these/can/use/wildcards/*",
            "/a/new/redirect/uri"
        ]
    }' |

# Pretty print the JSON response
json_pp

Note that your need to provide your client id both in the endpoint URL and within the body of the request.

⚠ Each time you modify your client, a new registration access token is generated. You need to keep track of your latest token to keep access to your client. ⚠

Registering an OIDC client

Creating your OpenID Connect client

Fetching your developer access token

Creating the client

Modifying your client

Collaboratory Community Apps