Merge pull request #11 from stianst/master
Moved client registration chapter to securing applications guide
This commit is contained in:
Stian Thorgersen
commit
cb63b4ed1b
2 changed files with 0 additions and 147 deletions
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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 <<fake/../../admin-console-permissions.adoc#_admin_permissions,Admin Permissions>> 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 <<fake/../../clients/oidc/service-accounts.adoc#_service_accounts,Service Accounts>> 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/<realm>/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/<realm>/clients-registrations/default/<client id>`.
|
||||
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/<realm>/clients-registrations/default/<client id>`.
|
||||
It will also return a new registration access token.
|
||||
|
||||
To delete the Client Representation then do a HTTP DELETE to: `auth/realms/<realm>/clients-registrations/default/<client id>`
|
||||
|
||||
==== {{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/<realm>/clients-registrations/install/<client id>`
|
||||
|
||||
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/<realm>/clients-registrations/oidc[/<client id>]`.
|
||||
|
||||
This endpoints can also be found in the OpenID Connect Discovery endpoint for the realm: `auth/realms/<realm>/.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/<realm>/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();
|
||||
----
|
||||
Loading…
Reference in a new issue