Summary

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

Details

Page properties

Content

...	...	@@ -1,1 +1,198 @@
1		-some content
	1	+Developers can extend the Collaboratory capabilities by providing applications to its community of users.
	2	+
	3	+This guide describes the steps to make this possible.
	4	+
	5	+{{{formatted}}}
	6	+
	7	+(((
	8	+div
	9	+)))
	10	+
	11	+== Becoming a contributor ==
	12	+
	13	+The first step is for you to **become a contributor**. Contributors can register and manage applications within the Community Apps Catalogue.
	14	+
	15	+Send an email to [[support@humanbrainproject.eu>>path:mailto:support@humanbrainproject.eu]] with a short summary of your intentions.
	16	+
	17	+The support team will apply the permissions to your user: your account will be upgraded with developers privileges the next time you will login.
	18	+
	19	+Only SGA2 accredited users will be automatically granted the contributor level.
	20	+
	21	+== Registering an application in the Catalogue ==
	22	+
	23	+Collab authors find applications to add to their collabs in the Community Apps Catalogue.
	24	+
	25	+{{error}}
	26	+TODO: describe the steps to register an app in the Catalogue
	27	+{{/error}}
	28	+
	29	+== Creating your OpenID Connect client ==
	30	+
	31	+The steps to create an OpenID Connect client are the following:
	32	+
	33	+1. get an access token from the `developer` client
	34	+1. use the token to call the create endpoint
	35	+1. save your registration access token for further modifications of your client
	36	+
	37	+=== Fetching your developer access token ===
	38	+
	39	+==== some h4 ====
	40	+
	41	+Getting your developer token is done in one simple step: authenticate against the developer client with the password grant.
	42	+
	43	+This can be achieved with this sample shell script:
	44	+
	45	+{{code language="bash"}}
	46	+# Gather username and password from user
	47	+echo '\nEnter your username' && read clb_dev_username &&
	48	+echo '\nEnter your password' && read -s clb_dev_pwd &&
	49	+
	50	+# Fetch the token
	51	+curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/protocol/openid-connect/token \
	52	+ -u developer: \
	53	+ -d 'grant_type=password' \
	54	+ -d "username=${clb_dev_username}" \
	55	+ -d "password=${clb_dev_pwd}" |
	56	+
	57	+# Prettify the JSON response
	58	+json_pp;
	59	+
	60	+# Erase the credentials from local variables
	61	+clb_dev_pwd='';clb_dev_username=''
	62	+{{/code}}
	63	+
	64	+The response will be similar to:
	65	+
	66	+{{code language="json"}}
	67	+{
	68	+ "access_token": "eyJhbGci...",
	69	+ "expires_in": 108000,
	70	+ "refresh_expires_in": 14400,
	71	+ "refresh_token": "eyJhbGci...",
	72	+ "token_type": "bearer",
	73	+ "not-before-policy": 1563261088,
	74	+ "session_state": "0ac3dfcd-aa5e-42eb-b333-2f73496b81f8",
	75	+ "scope": ""
	76	+}
	77	+{{/code}}
	78	+
	79	+Copy the "access_token" value, you will need if for the next step.
	80	+
	81	+=== Creating the client ===
	82	+
	83	+You can now create clients by sending a JSON representation to a specific endpoint:
	84	+
	85	+{{code language="bash"}}
	86	+# Set your developer token
	87	+clb_dev_token=...
	88	+
	89	+# Send the creation request
	90	+curl -X POST https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/ \
	91	+ -H "Authorization: Bearer ${clb_dev_token}" \
	92	+ -H 'Content-Type: application/json' \
	93	+ -d '{
	94	+ "clientId": "my-awesome-client",
	95	+ "name": "My Awesome App",
	96	+ "description": "This describes what my app is for end users",
	97	+ "rootUrl": "https://root.url.of.my.app",
	98	+ "baseUrl": "/relative/path/to/its/frontpage.html",
	99	+ "redirectUris": [
	100	+ "/relative/redirect/path",
	101	+ "/these/can/use/wildcards/*"
	102	+ ],
	103	+ "webOrigins": ["+"],
	104	+ "bearerOnly": false,
	105	+ "consentRequired": true,
	106	+ "standardFlowEnabled": true,
	107	+ "implicitFlowEnabled": true,
	108	+ "directAccessGrantsEnabled": false,
	109	+ "attributes": {
	110	+ "contacts": "first.contact@example.com; second.contact@example.com"
	111	+ }
	112	+ }' |
	113	+
	114	+# Prettify the JSON response
	115	+json_pp;
	116	+{{/code}}
	117	+
	118	+In case of success, the endpoint will return its representation of your client:
	119	+
	120	+{{code language="json"}}
	121	+{
	122	+ "defaultClientScopes" : [
	123	+ "web-origins",
	124	+ "roles"
	125	+ ],
	126	+ "redirectUris" : [
	127	+ "/relative/redirect/path",
	128	+ "/these/can/use/wildcards/*"
	129	+ ],
	130	+ "nodeReRegistrationTimeout" : -1,
	131	+ "rootUrl" : "https://root.url.of.my.app",
	132	+ "webOrigins" : [
	133	+ "+"
	134	+ ],
	135	+ "authenticationFlowBindingOverrides" : {},
	136	+ "baseUrl" : "/relative/path/to/its/frontpage.html",
	137	+ "description" : "This describes what my app is for end users",
	138	+ "notBefore" : 0,
	139	+ "frontchannelLogout" : false,
	140	+ "enabled" : true,
	141	+ "registrationAccessToken" : "eyJhbGciOi...",
	142	+ "consentRequired" : true,
	143	+ "fullScopeAllowed" : false,
	144	+ "clientAuthenticatorType" : "client-secret",
	145	+ "surrogateAuthRequired" : false,
	146	+ "directAccessGrantsEnabled" : false,
	147	+ "standardFlowEnabled" : true,
	148	+ "id" : "551b49a0-ec69-41af-9461-6c10fbc79a35",
	149	+ "attributes" : {
	150	+ "contacts" : "first.contact@example.com; second.contact@example.com"
	151	+ },
	152	+ "name" : "My Awesome App",
	153	+ "secret" : "your-client-secret",
	154	+ "publicClient" : false,
	155	+ "clientId" : "my-awesome-client",
	156	+ "optionalClientScopes" : [],
	157	+ "implicitFlowEnabled" : true,
	158	+ "protocol" : "openid-connect",
	159	+ "bearerOnly" : false,
	160	+ "serviceAccountsEnabled" : false
	161	+}
	162	+{{/code}}
	163	+
	164	+Among all the attributes, you should securely save:
	165	+
	166	+* your client **secret** ("secret" attribute): it is needed by your application to **authenticate to the IAM server** when making backend calls
	167	+* your client **registration access token** ("registrationAccessToken"): you will need it to authenticate when **modifying your client in the future**
	168	+
	169	+=== Modifying your client ===
	170	+
	171	+Update your client with a PUT request:
	172	+
	173	+{{code language="bash"}}
	174	+# Set your registration token and client id
	175	+clb_reg_token=...
	176	+
	177	+# Update the client
	178	+curl -X PUT https://iam.humanbrainproject.eu/auth/realms/hbp/clients-registrations/default/my-awesome-client \
	179	+ -H "Authorization: Bearer ${clb_reg_token}" \
	180	+ -H 'Content-Type: application/json' \
	181	+ -d '{
	182	+ "clientId": "my-awesome-client",
	183	+ "redirectUris": [
	184	+ "/relative/redirect/path",
	185	+ "/these/can/use/wildcards/*",
	186	+ "/a/new/redirect/uri"
	187	+ ]
	188	+ }' |
	189	+
	190	+# Prettify the JSON response
	191	+json_pp;
	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 will be generated. You need to track of your token changes to keep access to your client.   **/!\
	198	+{{/warning}}