From 22112e8d06fcd03c69d1f7305c4e819338bc6deb Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Thu, 2 Jun 2016 14:18:40 +0200 Subject: [PATCH] Moved client registration chapter to securing applications guide --- SUMMARY.adoc | 1 - topics/clients/client-registration.adoc | 146 ------------------------ 2 files changed, 147 deletions(-) delete mode 100755 topics/clients/client-registration.adoc diff --git a/SUMMARY.adoc b/SUMMARY.adoc index 5a4af888e2..3e08428378 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -42,7 +42,6 @@ ... link:topics/clients/saml/idp-initiated-login.adoc[IDP Initiated Login] ... link:topics/clients/saml/entity-descriptors.adoc[SAML Entity Descriptors] .. link:topics/clients/client-link.adoc[Client Links] - .. link:topics/clients/client-registration.adoc[Client Registration] .. link:topics/clients/protocol-mappers.adoc[Token and Assertion Mappings] .. link:topics/clients/installation.adoc[Generating Client Adapter Config] .. link:topics/clients/client-templates.adoc[Client Templates] diff --git a/topics/clients/client-registration.adoc b/topics/clients/client-registration.adoc deleted file mode 100755 index beab14f075..0000000000 --- a/topics/clients/client-registration.adoc +++ /dev/null @@ -1,146 +0,0 @@ -=== Client Registration - -In order for an application or service to utilize {{book.project.name}} it has to register a client in {{book.project.name}}. -An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through {{book.project.name}}'s client registration service. - -The Client Registration Service provides built-in support for {{book.project.name}} Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors. -It's also possible to plugin custom client registration providers if required. -The Client Registration Service endpoint is `auth/realms/\{realm-name}/clients-registrations/\{provider}`. - -The built-in supported `providers` are: - -* default -* install -* openid-connect -* saml2-entity-descriptor - -The following sections will describe how to use the different providers. - -==== Authentication - -To invoke the Client Registration Services you need a token. -The token can be a standard bearer token, a initial access token or a registration access token. - -===== Bearer Token - -The bearertoken can be issued on behalf of a user or a Service Account. -The following permissions are required to invoke the endpoints (see <> for more details): - -* create-client -+`manage-client` -* view-client -+`manage-client` -* manage-client - -If you are using a regular bearer token to create clients we recommend using a token from on behalf of a Service Account with only the `create-client` role. -See the <> section for more details. - -===== Initial Access Token - -The best approach to create new clients is by using initial access tokens. -An initial access token can only be used to create clients and has a configurable expiration as well as a configurable limit on how many clients can be created. - -An initial access token can be created through the admin console. -To create a new initial access token first select the realm in the admin console, then click on `Realm Settings` in the menu on the left, followed by `Initial Access Tokens` in the tabs displayed in the page. - -You will now be able to see any existing initial access tokens. -If you have access you can delete tokens that are no longer required. -You can only retrieve the value of the token when you are creating it. -To create a new token click on `Create`. -You can now optionally add how long the token should be valid, also how many clients can be created using the token. -After you click on `Save` the token value is displayed. -It is important that you copy/paste this token now as you won't be able to retrieve it later. -If you forget to copy/paste it, then delete the token and create another one. -The token value is used as a standard bearer token when invoking the Client Registration Services, by adding it to the Authorization header in the request. -For example: - -[source] ----- -Authorization: bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmMjJmNzQyYy04ZjNlLTQ2M.... ----- - -===== Registration Access Token - -When you create a client through the Client Registration Service the response will include a registration access token. -The registration access token provides access to retrieve the client configuration later, but also to update or delete the client. -The registration access token is included with the request in the same way as a bearer token or initial access token. -Registration access tokens are only valid once when it's used the response will include a new token. - -If a client was created outside of the Client Registration Service it won't have a registration access token associated with it. -You can create one through the admin console. -This can also be useful if you loose the token for a particular client. -To create a new token find the client in the admin console and click on `Credentials`. -Then click on `Generate registration access token`. - -==== {{book.project.name}} Representations - -The `default` client registration provider can be used to create, retrieve, update and delete a client. -It uses {{book.project.name}} Client Representation format which provides support for configuring clients exactly as they can be configured through the admin console, including for example configuring protocol mappers. - -To create a client create a Client Representation (JSON) then do a HTTP POST to: `auth/realms//clients-registrations/default`. -It will return a Client Representation that also includes the registration access token. -You should save the registration access token somewhere if you want to retrieve the config, update or delete the client later. - -To retrieve the Client Representation then do a HTTP GET to: `auth/realms//clients-registrations/default/`. -It will also return a new registration access token. - -To update the Client Representation then do a HTTP PUT to with the updated Client Representation to: `auth/realms//clients-registrations/default/`. -It will also return a new registration access token. - -To delete the Client Representation then do a HTTP DELETE to: `auth/realms//clients-registrations/default/` - -==== {{book.project.name}} Adapter Configuration - -The `installation` client registration provider can be used to retrieve the adapter configuration for a client. -In addition to token authentication you can also authenticate with client credentials using HTTP basic authentication. -To do this include the following header in the request: - -[source] ----- -Authorization: basic BASE64(client-id + ':' + client-secret) ----- - -To retrieve the Adapter Configuration then do a HTTP GET to: `auth/realms//clients-registrations/install/` - -No authentication is required for public clients. -This means that for the JavaScript adapter you can load the client configuration directly from {{book.project.name}} using the above URL. - -==== OpenID Connect Dynamic Client Registration - -{{book.project.name}} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://tools.ietf.org/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://tools.ietf.org/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol]. - -The endpoint to use these specifications to register clients in {{book.project.name}} is: `auth/realms//clients-registrations/oidc[/]`. - -This endpoints can also be found in the OpenID Connect Discovery endpoint for the realm: `auth/realms//.well-known/openid-configuration`. - -==== SAML Entity Descriptors - -The SAML Entity Descriptor endpoint only supports using SAML v2 Entity Descriptors to create clients. -It doesn't support retrieving, updating or deleting clients. -For those operations the {{book.project.name}} representation endpoints should be used. -When creating a client a {{book.project.name}} Client Representation is returned with details about the created client, including a registration access token. - -To create a client do a HTTP POST with the SAML Entity Descriptor to: `auth/realms//clients-registrations/saml2-entity-descriptor`. - -==== Client Registration Java API - -The Client Registration Java API makes it easy to use the Client Registration Service using Java. -To use include the dependency `org.keycloak:keycloak-client-registration-api:>VERSION<` from Maven. - -For full instructions on using the Client Registration refer to the JavaDocs. -Below is an example of creating a client: - -[source,java] ----- -String initialAccessToken = "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmMjJmNzQyYy04ZjNlLTQ2M...."; - -ClientRepresentation client = new ClientRepresentation(); -client.setClientId(CLIENT_ID); - -ClientRegistration reg = ClientRegistration.create().url("http://keycloak/auth/realms/myrealm/clients").build(); -reg.auth(Auth.token(initialAccessToken)); - -client = reg.create(client); - -String registrationAccessToken = client.getRegistrationAccessToken(); -----