1. Registering an OIDC client

1

== OAuth 2 Flows ==

2

3

Must read before starting

4

5

It's very important to choose the right type of clients and to understand the various OAuth flows.

6

7

A very good documentation is this one :

8

9

[[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]]

and another one

[[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]]

14

15

Here is a quick summary of which flow is designed to be used in a given scenario:

16

17

* server-to-server (Client Credentials Flow):

18

** standardFlowEnabled : false

19

** consentRequired : false

20

** redirectUri empty

21

** serviceAccountEnabled : true

22

23

so user can't login with this client, [[and the client must have the serviceAccount property set to true >>https://wiki.ebrains.eu/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/Using%20your%20OIDC%20client%20as%20a%20service%20account/]]

24

25

* server-side app (Authorization Code Flow also called Standard Flow, it's the regular flow to establish a login page on your website accessible by your users):

26

** standardFlowEnabled : true

27

** consentRequired : true

28

** redirectUri : not empty, not localhost, https only

29

30

* SPA: Single-Page-Application, basically app without backend, public client with Authorization Code Flow and PKCE enforcement by us

31

** publicClient : true

32

** standardFlowEnabled : true

33

** consentRequired : true

34

** redirectUri : not empty, not localhost, https only

35

36

* mobile: Authorization Code Flow

37

** Same as SPA public or confidential depending if the mobile App use a backend

38

39

Note : We are not allowing Implicit Flow, we are not allowing Standard flow without consentRequired and redirectUri either, for security reason. FYI, your public client for SPA usage will be enforced automatically by us with the [[PKCE>>https://oauth.net/2/pkce/]] feature.

== Abstract ==

This wiki page is for service providers whose apps need to authenticate with the EBRAINS Single Sign-On. EBRAINS users need to be in the [["service providers" Group>>https://wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers]] to access to manage an OIDC client.

44

45

A previous version of this documentation explained how to create an OIDC Client using the native Keycloak API. It was a bit complex for users. They had to fetch a specific developer access token, then create the OIDC client, and safely store the registrationAccessToken and safely store a new token after every one of their updates. There were limitations on scope editions. There was no notion of OIDC client ownership making it difficult to manage who could edit settings for the OIDC client. And there was no option to grant access to the OIDC client to a limited set of EBRAINS users.

46

\\All these issues have been solved with the new OIDC Client API provided in the Collaboratory API. OIDC client owners can now use their usual collab access token (e.g. from a notebook in the Collaboratory Lab) to create and manage their OIDC Client. They no longer have to safely store a registrationAccessToken. They can provide a list of maintainers that are allowed to update the OIDC client. And they can also choose which end users can be granted access via their OIDC client.

47

\\This documentation describes the available endpoints and the JSON format excepted by the API. A more concrete example is also provided in a Lab notebook.

48

49

== Lab notebook to create and manage your client ==

50

51

(% class="wikigeneratedid" %)

52

A live example of OIDC Client creation is available **[[here>>https://lab.ch.ebrains.eu/hub/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb]] **to be run in the Collaboratory Lab.

53

54

(% class="wikigeneratedid" %)

55

The next steps in this documentation reproduce the content of the notebook. We strongly recommend that service providers use this notebook to create their OIDC client. It's the easiest way to avoid any mistake.

56

57

58

== Create a localhost client for developement on our integration enviroment ==

59

60

You can't create client with redirectUri localhost in production. If you want to create a client for development purpose, please use our integration environement

61

\\Registration on integration environement : [[https:~~/~~/iam-int.ebrains.eu/register>>https://iam-int.ebrains.eu/register]]

62

63

64

Wiki group to access lab : [[https:~~/~~/wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-lab~~-~~-access>>https://wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-lab--access]]

65

Wiki group to access OIDC API : [[https:~~/~~/wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam~~-~~-service-providers>>https://wiki-int.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers]]

66

67

For now, contact our support to be granted on lab-int and get developer accreditation

68

\\Notebook to create client : [[https:~~/~~/lab-int.ebrains.eu/hub/user-redirect/lab/tree/shared/%EF%BB%BFThe%20Collaboratory/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb>>https://lab-int.ebrains.eu/hub/user-redirect/lab/tree/shared/%EF%BB%BFThe%20Collaboratory/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb]]

== Endpoints ==

(% class="box infomessage" %)

73

(((

74

POST : https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients

75

PUT : https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}

76

GET : https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}

77

)))

78

79

The POST/PUT API endpoints use the same JSON format to describe the OIDC client.

80

81

The GET API endpoint returns a valid JSON format, which can be edited and used to update an OIDC client. It's the recommended way of updating an OIDC client: first fetch your OIDC client's info, then edit the JSON. This reduces the risk of forgetting data in the JSON of POST/PUT call which would delete the missing data from the OIDC client configuration.

== JSON Format ==

Find below an example JSON format and an explanation of its fields.

----

{

"client": {

"clientId": "tutorialOidcApi",

93

"name": "Tutorial OIDC API",

94

"description": "A sample client demo for the OIDC API documentation",

95

"rootUrl": "https://example.org",

96

"baseUrl": "https://example.org",

97

"redirectUris": [

98

"https://example.org/login/*"

99

],

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", "email"],

109

"optionalClientScopes": ["profile","team","group"]

110

},

111

"maintainers": ["messines","bougault"],

112

"featureAuthenticate" : false,

113

"accessDeniedToGuests" : false

}

=== client ===

The JSON provided to the OIDC app API must contain a "client" object. It's the same JSON as in the previous versions of the documentation using the Keycloak native API. You can use all the attributes available in the ClientRepresentation object natively used by Keycloak and [[described here>>https://www.keycloak.org/docs-api/15.0/rest-api/index.html#_clientrepresentation]].

=== maintainers ===

This list field is optional. The OIDC client owner can provide a list of maintainers. The values in the list must be valid usernames of EBRAINS users. Even if this field is not provided, the OIDC client can always also be maintained by its owner. An OIDC client is now automatically configured with an owner property which stores the username of the EBRAINS user creating the OIDC client.

124

125

=== featureAuthenticate ===

126

127

This boolean field is optional. If it is not provided, it defaults to **false**. If set to true, EBRAINS users will not be able to gain access to your OIDC client unless they are in a Collaboratory Group or Collaboratory Unit which has the "feature:authenticate" role for your OIDC client.

128

129

Service providers wanting to use this feature should set it to true in the JSON request to create/update their OIDC client. They should then use the API endpoints below to grant (PUT) or revoke (DELETE) access.

PUT/DELETE: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/groups/**{groupsName}|**

134

PUT/DELETE: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/units/**{unitPath}**

135

\\__Example to grant access to HBP members__

136

137

PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/units/**all:projects:hbp**

138

139

__Example to grant access to TVB Workshop attendees__

140

141

PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/groups/**TVB-Workshops**

142

143

144

EBRAINS users can visit [[https:~~/~~/wiki.ebrains.eu/bin/view/Identity>>https://wiki.ebrains.eu/bin/view/Identity]] and from there browse Units to find the relevant unitPath in the Unit tree.

145

146

A more complete documentation on [[How to grant access is available in the notebook>>https://lab.ch.ebrains.eu/hub/user-redirect/lab/tree/shared/Collaboratory%20Community%20Apps/Managing%20an%20OpenID%20Connect%20client%20-%20V2.ipynb]]. If you don't feel confident in managing specifically access to your client, the easiest is maybe to let your authentication open to all EBRAINS users as it is currently the case by letting //featureAuthenticate //property to false.

147

148

149

__**Warning**__**:** if you switch featureAuthenticate from true to false, all the Group/Unit specific accesses that were configured will be lost and will have to be granted again if you switch from false to true again.

150

151

=== accessDeniedToGuests ===

152

153

This boolean field is optional. If it is not provided, it defaults to **true**, meaning that Guest users won't be able to access your OIDC client.

154

\\Service providers who want to provide access to EBRAINS guest accounts can set this field to false. Use of EBRAINS resources by EBRAINS guests accounts is the service provider's responsibility. Guest users might be insufficiently identified, might not be legally liable, might not be part of the target audience of the EBRAINS platform. See [[Guest accounts>>doc:Collabs.the-collaboratory.Documentation Wiki.FAQ.Create guests accounts.WebHome]] for more information before granting such an access and contact [[EBRAINS Support>>https://ebrains.eu/support]] in case of doubt.

155

156

== How to GET and UPDATE your client ==

157

158

Service providers who want to see your OIDC client settings can GET the API endpoint as shown below, with their access token, e.g. the token from the Collaboratory Lab.

159

160

161

GET: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/{clientId}/

162

163

e.g. GET: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/

164

\\The response will look like:

{

"client": {

"id": "tutorialOidcApi",

170

"clientId": "tutorialOidcApi",

171

"name": "Tutorial OIDC API",

172

"description": "A sample client demo for the OIDC API documentation",

173

"rootUrl": "https://example.org",

174

"adminUrl": null,

175

"baseUrl": "https://example.org",

176

"surrogateAuthRequired": false,

177

"enabled": true,

178

"alwaysDisplayInConsole": false,

179

"clientAuthenticatorType": "client-secret",

180

"secret": "IooQSAmrbPUqYgHdkklBMPsIBKlupUi",

181

"registrationAccessToken": null,

182

"redirectUris": [

183

"https://example.org/login/*"

184

],

185

"webOrigins": [

186

"https://example.org"

187

],

188

"bearerOnly": false,

189

"consentRequired": true,

190

"standardFlowEnabled": true,

191

"implicitFlowEnabled": false,

192

"directAccessGrantsEnabled": false,

193

"serviceAccountsEnabled": false,

194

"publicClient": false,

195

"frontchannelLogout": false,

196

"protocol": "openid-connect",

197

"attributes": {

198

"contacts": "first.contact@example.com; second.contact@example.com"

199

},

200

"authenticationFlowBindingOverrides": {},

201

"fullScopeAllowed": false,

202

"nodeReRegistrationTimeout": -1,

203

"registeredNodes": null,

204

"defaultClientScopes": [

"openid",

"email"

],

"optionalClientScopes": [

"profile",

"team",

"group"

],

"access": null,

"origin": null

},

"owner": "messines",

"maintainers": [

"messines",

"bougault"

],

"accessDeniedToGuests": false,

222

"featureAuthenticate": false,

"grantedAccess": {

"users": [],

"units": [],

"groups": []

},

"featureAuthenticateIntValue": 0,

229

"guestPropertyIntValue": 0

}

Then to update the OIDC client settings, the easiest and recommended way is to copy the JSON received from the GET request, to edit it, and run a PUT request on the OIDC client endpoint with the JSON added as body of the request.

234

235

e.g. PUT: https:~/~/wiki.ebrains.eu/rest/v1/oidc/clients/tutorialOidcApi/

236

\\The following attributes should be removed before resending the JSON to the PUT endpoint, or they will simply be ignored:

237

238

* grantedAccess

239

* featureAuthenticateIntValue

240

* guestPropertyIntValue

241

* owner

242

243

To change the owner of an OIDC client, the current owner should contact [[EBRAINS support>>https://ebrains.eu/support]].

244

245

== Using your new OIDC client as a service account ==

246

247

To use your new OIDC client as a service account, please [[read our tutorial>>path:/bin/view/Collabs/the-collaboratory/Documentation%20IAM/FAQ/Using%20your%20OIDC%20client%20as%20a%20service%20account/]] on how to do this.

Wiki source code of 1. Registering an OIDC client

The Collaboratory