Registering an OIDC client

Version 1.1 by villemai on 2020/05/04 16:15

Creating your OpenID Connect client

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

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

Note that a notebook is available to help you create and modify your OIDC client.

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
echo '\nEnter your username' && read clb_dev_username &&
echo '\nEnter your password' && read -s 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}" |
 
# Prettify 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": ""
}

Copy 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=...

# 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"
        }
    }' |

# Prettify 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 backend 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=...

# Update the client
curl -X PUT https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/my-awesome-client \
  -H "Authorization: Bearer ${clb_reg_token}" \
  -H 'Content-Type: application/json' \
  -d '{
        "clientId": "my-awesome-client",
        "redirectUris": [
            "/relative/redirect/path",
            "/these/can/use/wildcards/*",
            "/a/new/redirect/uri"
        ]
    }' |

# Prettify 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 will be generated. You need to keep track of your token changes to keep access to your client.   /!\

 

Table of content