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

== UI to create and manage your clients ==

50

51

The newest addition to the OIDC client creation process on the Collaboratory is a UI to help you manage, create and update your clients. You can find this by visiting [[https:~~/~~/wiki.ebrains.eu/bin/view/OIDC/>>https://wiki.ebrains.eu/bin/view/OIDC/]].

52

\\To create a new OIDC client click on the "Create new client" button as shown in the following image~:

53

54

[[image:image-20230209111255-1.png]]

55

56

(% class="wikigeneratedid" %)

57

The UI will explain all of the options you can choose from. To update any client alraedy existing, click on the client in the list. For example, in the above example, if I wanted to update the client "pauls test client" I would click on that entry in the list.

58

59

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

60

61

(% class="wikigeneratedid" %)

62

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.

63

64

(% class="wikigeneratedid" %)

65

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.

66

67

68

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

69

70

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

71

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

72

73

74

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

75

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

76

77

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

78

\\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" %)

83

(((

84

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

85

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

86

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

87

)))

88

89

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

90

91

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

103

"name": "Tutorial OIDC API",

104

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

105

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

106

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

107

"redirectUris": [

108

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

109

],

110

"bearerOnly": false,

111

"consentRequired": true,

112

"standardFlowEnabled": true,

113

"implicitFlowEnabled": false,

114

"directAccessGrantsEnabled": false,

115

"attributes": {

116

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

117

},

118

"defaultClientScopes": ["openid", "email"],

119

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

120

},

121

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

122

"featureAuthenticate" : false,

123

"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.

134

135

=== featureAuthenticate ===

136

137

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.

138

139

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}**

144

145

146

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

147

\\__Example to grant access to HBP members__

148

149

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

150

151

__Example to grant access to TVB Workshop attendees__

152

153

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

154

155

156

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.

157

158

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.

159

160

161

__**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.

162

163

=== accessDeniedToGuests ===

164

165

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.

166

\\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.

167

168

== How to GET and UPDATE your client ==

169

170

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.

171

172

173

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

174

175

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

176

\\The response will look like:

{

"client": {

"id": "tutorialOidcApi",

182

"clientId": "tutorialOidcApi",

183

"name": "Tutorial OIDC API",

184

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

185

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

186

"adminUrl": null,

187

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

188

"surrogateAuthRequired": false,

189

"enabled": true,

190

"alwaysDisplayInConsole": false,

191

"clientAuthenticatorType": "client-secret",

192

"secret": "IooQSAmrbPUqYgHdkklBMPsIBKlupUi",

193

"registrationAccessToken": null,

194

"redirectUris": [

195

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

196

],

197

"webOrigins": [

198

"https://example.org"

199

],

200

"bearerOnly": false,

201

"consentRequired": true,

202

"standardFlowEnabled": true,

203

"implicitFlowEnabled": false,

204

"directAccessGrantsEnabled": false,

205

"serviceAccountsEnabled": false,

206

"publicClient": false,

207

"frontchannelLogout": false,

208

"protocol": "openid-connect",

209

"attributes": {

210

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

211

},

212

"authenticationFlowBindingOverrides": {},

213

"fullScopeAllowed": false,

214

"nodeReRegistrationTimeout": -1,

215

"registeredNodes": null,

216

"defaultClientScopes": [

"openid",

"email"

],

"optionalClientScopes": [

"profile",

"team",

"group"

],

"access": null,

"origin": null

},

"owner": "messines",

"maintainers": [

"messines",

"bougault"

],

"accessDeniedToGuests": false,

234

"featureAuthenticate": false,

"grantedAccess": {

"users": [],

"units": [],

"groups": []

},

"featureAuthenticateIntValue": 0,

241

"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.

246

247

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

248

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

249

250

* grantedAccess

251

* featureAuthenticateIntValue

252

* guestPropertyIntValue

253

* owner

254

255

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

256

257

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

258

259

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