Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

...	...	@@ -1,2 +1,198 @@
1		-Please find the new documentation here
2		-\\[[https:~~/~~/wiki.ebrains.eu/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/OIDC%20Clients%20explained/1.%20Registering%20an%20OIDC%20client%20v2/>>https://wiki.ebrains.eu/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/OIDC%20Clients%20explained/1.%20Registering%20an%20OIDC%20client%20v2/]]
	1	+== Must read before starting ==
	2	+
	3	+It's very important to choose the right type of clients and to understand the various OAuth flows.
	4	+
	5	+A very good documentation is this one :
	6	+
	7	+[[https:~~/~~/auth0.com/docs/authorization/which-oauth-2-0-flow-should-i-use>>url:https://auth0.com/docs/authorization/which-oauth-2-0-flow-should-i-use]]
	8	+
	9	+and another one
	10	+
	11	+[[https:~~/~~/dzone.com/articles/the-right-flow-for-the-job-which-oauth-20-flow-sho>>url:https://dzone.com/articles/the-right-flow-for-the-job-which-oauth-20-flow-sho]]
	12	+
	13	+== Creating your OpenID Connect client ==
	14	+
	15	+The steps to create an OpenID Connect (OIDC) client are the following:
	16	+
	17	+1. Ask the developer accreditation to be authorize to create client
	18	+1. get an access token from the `developer` client
	19	+1. save your registration access token for further modifications of your client
	20	+1. use the token to call the create endpoint
	21	+
	22	+==== Easiest way to create a client ====
	23	+
	24	+**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.
	25	+
	26	+[[https:~~/~~/lab.ebrains.eu/user/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client.ipynb>>https://lab.ebrains.eu/user/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client.ipynb]]
	27	+
	28	+=== Ask for developer accreditation ===
	29	+
	30	+To be authorize to create an OIDC client you have to be accredited as developer.
	31	+
	32	+Please go on this page and "Request to join" the group [[https:~~/~~/wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam~~-~~-service-providers>>https://wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers]]
	33	+
	34	+We will quickly process your request and you will be able to create an OIDC client
	35	+
	36	+=== Fetching your developer access token ===
	37	+
	38	+Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
	39	+
	40	+This can be achieved with this sample shell script:
	41	+
	42	+{{code language="bash"}}
	43	+# Gather username and password from user
	44	+read -p 'Enter your username: ' clb_dev_username
	45	+read -s -p 'Enter your password: ' clb_dev_pwd
	46	+
	47	+# Fetch the token
	48	+curl -X POST https://iam.ebrains.eu/auth/realms/hbp/protocol/openid-connect/token \
	49	+ -u developer: \
	50	+ -d 'grant_type=password' \
	51	+ --data-urlencode "username=${clb_dev_username}" \
	52	+ --data-urlencode "password=${clb_dev_pwd}" |
	53	+
	54	+# and pretty-print the JSON response
	55	+json_pp
	56	+
	57	+# Erase the credentials from local variables
	58	+clb_dev_pwd=''; clb_dev_username=''
	59	+{{/code}}
	60	+
	61	+The response will be similar to:
	62	+
	63	+{{code language="json"}}
	64	+{
	65	+ "access_token": "eyJhbGci...",
	66	+ "expires_in": 108000,
	67	+ "refresh_expires_in": 14400,
	68	+ "refresh_token": "eyJhbGci...",
	69	+ "token_type": "bearer",
	70	+ "not-before-policy": 1563261088,
	71	+ "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
	72	+ "scope": ""
	73	+}
	74	+{{/code}}
	75	+
	76	+Store a copy of the "access_token" value. You will need if for the next step.
	77	+
	78	+=== Creating the client ===
	79	+
	80	+You can now create clients by sending a JSON representation to a specific endpoint:
	81	+
	82	+{{code language="bash"}}
	83	+# Set your developer token
	84	+clb_dev_token="eyJhbGci..."
	85	+
	86	+# Send the creation request
	87	+curl -X POST https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/ \
	88	+ -H "Authorization: Bearer ${clb_dev_token}" \
	89	+ -H 'Content-Type: application/json' \
	90	+ -d '{ "clientId": "your_client_id",
	91	+ "name": "Collaboratory workshop demo client edited",
	92	+ "description": "This describes what my app is for end users",
	93	+ "rootUrl": "https://example.org",
	94	+ "baseUrl": "https://example.org",
	95	+ "redirectUris": [
	96	+ "/login/*",
	97	+ "https://example.org/login/*"
	98	+ ],
	99	+ "webOrigins":["http://localhost:8080","https://example.org","+"],
	100	+ "bearerOnly": False,
	101	+ "consentRequired": True,
	102	+ "standardFlowEnabled": True,
	103	+ "implicitFlowEnabled": False,
	104	+ "directAccessGrantsEnabled": False,
	105	+ "attributes": {
	106	+ "contacts": "first.contact@example.com; second.contact@example.com"
	107	+ },
	108	+ "defaultClientScopes": ["openid","profile","email","roles"],
	109	+ "optionalClientScopes": ["team","group"]
	110	+ }' |
	111	+
	112	+# Pretty print the JSON response
	113	+json_pp;
	114	+{{/code}}
	115	+
	116	+In case of success, the endpoint will return its representation of your client:
	117	+
	118	+{{code language="json"}}
	119	+{
	120	+ "defaultClientScopes" : [
	121	+ "web-origins",
	122	+ "roles"
	123	+ ],
	124	+ "redirectUris" : [
	125	+ "/relative/redirect/path",
	126	+ "/these/can/use/wildcards/*"
	127	+ ],
	128	+ "nodeReRegistrationTimeout" : -1,
	129	+ "rootUrl" : "https://root.url.of.my.app",
	130	+ "webOrigins" : [
	131	+ "+"
	132	+ ],
	133	+ "authenticationFlowBindingOverrides" : {},
	134	+ "baseUrl" : "/relative/path/to/its/frontpage.html",
	135	+ "description" : "This describes what my app is for end users",
	136	+ "notBefore" : 0,
	137	+ "frontchannelLogout" : false,
	138	+ "enabled" : true,
	139	+ "registrationAccessToken" : "eyJhbGciOi...",
	140	+ "consentRequired" : true,
	141	+ "fullScopeAllowed" : false,
	142	+ "clientAuthenticatorType" : "client-secret",
	143	+ "surrogateAuthRequired" : false,
	144	+ "directAccessGrantsEnabled" : false,
	145	+ "standardFlowEnabled" : true,
	146	+ "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
	147	+ "attributes" : {
	148	+ "contacts" : "first.contact@example.com; second.contact@example.com"
	149	+ },
	150	+ "name" : "My Awesome App",
	151	+ "secret" : "your-client-secret",
	152	+ "publicClient" : false,
	153	+ "clientId" : "my-awesome-client",
	154	+ "optionalClientScopes" : [],
	155	+ "implicitFlowEnabled" : true,
	156	+ "protocol" : "openid-connect",
	157	+ "bearerOnly" : false,
	158	+ "serviceAccountsEnabled" : false
	159	+}
	160	+{{/code}}
	161	+
	162	+Among all the attributes, you should securely save:
	163	+
	164	+* your client **secret** ("secret" attribute): it is needed by your application to **authenticate to the IAM server** when making back-end calls
	165	+* your client **registration access token** ("registrationAccessToken"): you will need it to authenticate when **modifying your client in the future**
	166	+
	167	+=== Modifying your client ===
	168	+
	169	+Update your client with a PUT request:
	170	+
	171	+{{code language="bash"}}
	172	+# Set your registration token and client id
	173	+clb_reg_token="eyJhbGciOi..."
	174	+clb_client_id="my-awesome-client"
	175	+
	176	+# Update the client. Note that the client ID appears both in the endpoint URL and in the body of the request.
	177	+curl -X PUT https://iam.ebrains.eu/auth/realms/hbp/clients-registrations/default/${clb_client_id} \
	178	+ -H "Authorization: Bearer ${clb_reg_token}" \
	179	+ -H 'Content-Type: application/json' \
	180	+ -d '{
	181	+ "clientId": "'${clb_client_id}'",
	182	+ "redirectUris": [
	183	+ "/relative/redirect/path",
	184	+ "/these/can/use/wildcards/*",
	185	+ "/a/new/redirect/uri"
	186	+ ]
	187	+ }' |
	188	+
	189	+# Pretty print the JSON response
	190	+json_pp
	191	+
	192	+{{/code}}
	193	+
	194	+ Note that your need to provide your client id both in the endpoint URL and within the body of the request.
	195	+
	196	+{{warning}}
	197	+**⚠  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.  ⚠**
	198	+{{/warning}}