Must read before starting
It's very important to choose the right type of clients and to understand the various OAuth flows.
A very good documentation is this one :
https://auth0.com/docs/authorization/which-oauth-2-0-flow-should-i-use
and another one
https://dzone.com/articles/the-right-flow-for-the-job-which-oauth-20-flow-sho
Creating your OpenID Connect client
The steps to create an OpenID Connect (OIDC) client are the following:
- Ask the developer accreditation to be authorize to create client
- 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
Easiest way to create a client
A live exemple of client ID creation is available here on our lab, you can perfectly use this notebook to create your client, the next steps in this documentation reproduce the content of the notebook. The easiest solution as a user is to use this notebook to create a client and avoid human error while executing curl request manually.
Ask for developer accreditation
To be authorize to create an OIDC client you have to be accredited as developer.
Please go on this page and "Request to join" the group https://wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers
We will quickly process your request and you will be able to create an 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:
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:
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": "your_client_id",
"name": "Collaboratory workshop demo client edited",
"description": "This describes what my app is for end users",
"rootUrl": "https://example.org",
"baseUrl": "https://example.org",
"redirectUris": [
"/login/*",
"https://example.org/login/*"
],
"webOrigins":["http://localhost:8080","https://example.org","+"],
"bearerOnly": False,
"consentRequired": True,
"standardFlowEnabled": True,
"implicitFlowEnabled": False,
"directAccessGrantsEnabled": False,
"attributes": {
"contacts": "first.contact@example.com; second.contact@example.com"
},
"defaultClientScopes": ["openid","profile","email","roles"],
"optionalClientScopes": ["team","group"]
}' |
# 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:
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.