more clients

SUMMARY.adoc

@@ -36,13 +36,14 @@
  .. link:topics/sso-protocols/saml-vs-oidc.adoc[OIDC vs. SAML]
  . link:topics/clients.adoc[Managing Clients]
  .. link:topics/clients/client-oidc.adoc[OIDC Clients]
+ ... link:topics/clients/oidc/confidential.adoc[Confidential Client Credentials]
+ ... link:topics/clients/service-accounts.adoc[Service Accounts]
  .. link:topics/clients/client-saml.adoc[SAML Clients]
  ... 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/service-accounts.adoc[Service Accounts]
- .. link:topics/clients/protocol-mappers.adoc[Protocol Mappers]
+ .. link:topics/clients/protocol-mappers.adoc[Token and Assertion Mappings]
  . link:topics/admin-permissions.adoc[Master Admin Access Control]
  . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
  . link:topics/identity-broker.adoc[Identity Broker]

topics/clients/client-link.adoc

@@ -1,20 +1,7 @@
-= Clients
-:doctype: book
-:sectnums:
-:toc: left
-:icons: font
-:experimental:
-:sourcedir: .
 
-Keycloak provides support for managing Clients. 
+=== Client Links
 
-== Client Config
-
-Keycloak supports flexible configuration of Clients. 
-
-=== Redirect Endpoint
-
-For scenarios where one wants to link from one client to another, Keycloak provides a special redirect endpoint: `/realms/realm_name/clients/client_id/redirect`. 
+For scenarios where one wants to link from one client to another, {{book.project.name}} provides a special redirect endpoint: `/realms/realm_name/clients/\{client-id}/redirect`.
 
 If a client accesses this endpoint via an `HTTP GET` request, Keycloak returns the configured base URL for the provided Client and Realm in the form of an `HTTP 307` (Temporary Redirect) via the response's `Location` header. 
 
@@ -25,8 +12,8 @@ As an example, given the realm `master` and the client-id `account`:
 
 [source]
 ----
-http://keycloak-host:keycloak-port/auth/realms/master/clients/account/redirect
+http://host:port/auth/realms/master/clients/account/redirect
 ----               
-Would temporarily redirect to: http://keycloak-host:keycloak-port/auth/realms/master/account
+Would temporarily redirect to: http://host:port/auth/realms/master/account
 
 

topics/clients/client-oidc.adoc

@@ -52,6 +52,7 @@ If this is on, then users will get a consent page which asks the user if they gr
 display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to.
 If you've ever done a social login to Google, you'll often see a similar page.  {{book.project.name}} provides the same functionality.
 
+[[_access-type]]
 *Access Type*
 
 This defines the type of the OIDC client.

topics/clients/client-registration.adoc

@@ -1,11 +1,11 @@
-= Client Registration
+=== Client Registration
 
-In order for an application or service to utilize Keycloak it has to register a client in Keycloak.
-An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through Keycloak's client registration service. 
+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 Keycloak Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors.
+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 `<KEYCLOAK URL>/realms/<realm>/clients-registrations/<provider>`. 
+The Client Registration Service endpoint is `auth/realms/\{realm-name}/clients-registrations/\{provider}`.
 
 The built-in supported `providers` are: 
 
@@ -16,12 +16,12 @@ The built-in supported `providers` are:
 
 The following sections will describe how to use the different providers. 
 
-== Authentication
+==== 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
+===== 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 <<_admin_permissions,Admin Permissions>> for more details): 
@@ -32,9 +32,9 @@ The following permissions are required to invoke the endpoints (see <<_admin_per
 +`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 <<_service_accounts,Service Account>> section for more details. 
+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 <<oidc/service-accounts.adoc#_service_accounts,Service Accounst>> section for more details.
 
-=== Initial Access Token
+===== 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. 
@@ -58,7 +58,7 @@ For example:
 Authorization: bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmMjJmNzQyYy04ZjNlLTQ2M....
 ----            
 
-=== Registration Access Token
+===== 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.
@@ -71,24 +71,24 @@ 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`. 
 
-== Keycloak Representations
+==== {{book.project.name}} Representations
 
 The `default` client registration provider can be used to create, retrieve, update and delete a client.
-It uses Keycloaks 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. 
+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: `<KEYCLOAK URL>/realms/<realm>/clients-registrations/default`.
+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: `<KEYCLOAK URL>/realms/<realm>/clients-registrations/default/<client id>`.
+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: `<KEYCLOAK URL>/realms/<realm>/clients-registrations/default/<client id>`.
+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: `<KEYCLOAK URL>/realms/<realm>/clients-registrations/default/<client id>`        
+To delete the Client Representation then do a HTTP DELETE to: `auth/realms/<realm>/clients-registrations/default/<client id>`
 
-== Keycloak Adapter Configuration
+==== {{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.
@@ -99,29 +99,29 @@ To do this include the following header in the request:
 Authorization: basic BASE64(client-id + ':' + client-secret)
 ----        
 
-To retrieve the Adapter Configuration then do a HTTP GET to: `<KEYCLOAK URL>//realms/<realm>/clients-registrations/install/<client id>`        
+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 Keycloak using the above URL. 
+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
+==== OpenID Connect Dynamic Client Registration
 
-Keycloak 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]. 
+{{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 Keycloak is: `<KEYCLOAK URL>/realms/<realm>/clients-registrations/oidc[/<client id>]`. 
+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: `<KEYCLOAK URL>/realms/<realm>/.well-known/openid-configuration`. 
+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
+==== 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 Keycloak representation endpoints should be used.
-When creating a client a Keycloak Client Representation is returned with details about the created client, including a registration access token. 
+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: `<KEYCLOAK URL>/realms/<realm>/clients-registrations/saml2-entity-descriptor`. 
+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
+==== 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. 

topics/clients/oidc/confidential.adoc

@@ -0,0 +1,41 @@
+[[_client-credentials]]
+
+==== Confidential Client Credentials
+
+If you've set the client's <<fake/../client-oidc.adoc#_access-type, _access type_>> to `confidential` in the client's
+`Settings` tab, a new `Credentials` tab will show up. As part of dealing with this
+type of client you have to configure the client's credentials.
+
+.Credentials Tab
+image:../../../{{book.images}}/client-credentials.png[]
+
+The `Client Authenticator` list box is the type of credential you are going to use for your confidential client.
+It defaults to client ID and secret.  The secret is automatically generated for you and the `Regenerate Secret`
+button allows you to recreate this secret if you want or need to.
+
+Alternatively, you can opt to use a signed Json Web Token (JWT) instead of a secret.
+
+.Signed JWT
+image:../../../{{book.images}}/client-credentials-jwt.png[]
+
+When choosing this credential type you will have to also generate a private key and certificate for the client.  The private key
+will be used to sign the JWT, while the certificate is used by the server to verify the signature.  Click on the
+`Generate new keys and certificate` button to start this process.
+
+.Generate Keys
+image:../../../{{book.images}}/generate-client-keys.png[]
+
+When you generate these keys, {{book.project.name}} will store the certificate, and you'll need to download the private key
+and certificate for your client to use.  Pick the archive format you want and specify the password for the private key
+and store.
+
+You can also opt to
+generate these via an external tool and just import the client's certificate.
+
+.Import Certificate
+image:../../../{{book.images}}/import-client-cert.png[]
+
+There's multiple formats you can import from, just choose the archive format you have the certificate stored in,
+select the file, and click the `Import` button.
+
+

topics/clients/oidc/service-accounts.adoc

@@ -1,17 +1,21 @@
-= Service Accounts
+[[_service-accounts]]
 
-Keycloak allows you to obtain an access token dedicated to some Client Application (not to any user). See http://tools.ietf.org/html/rfc6749#section-4.4[Client Credentials Grant]
-from OAuth 2.0 spec.
+=== Service Accounts
 
-To use it you must have registered a valid confidential Client and you need to check the switch `Service Accounts Enabled` in Keycloak admin console for this client.
+Each OIDC client has a built in _service account_ which allows them to obtain an access token.
+This is covered in the OAuth 2.0 specifiation under <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Client Credentials Grant>>
+To use this feature you must set the <<client-oidc.adoc#_access-type, Access Type>> of your client to `confidential`.  When you do this,
+the `Service Accounts Enabled` switch will appear.  You need to turn on this switch.  Also make sure that you have
+configured your <<confidential.adoc#_client-credentials, client credentials>>.
+
+To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in Keycloak admin console for this client.
 In tab `Service Account Roles` you can configure the roles available to the service account retrieved on behalf of this client.
 Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are intersection of scopes and the service account roles. 
 
-The REST URL to invoke on is `/{keycloak-root}/realms/{realm-name}/protocol/openid-connect/token`.
+The REST URL to invoke on is `/\{server-root-usualy-auth}/realms/\{realm-name}/protocol/openid-connect/token`.
 Invoking on this URL is a POST request and requires you to post the client credentials.
 By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate client with signed JWT assertion or any other custom mechanism for client authentication.
-See <<_client_authentication,Client Authentication>> section for more details.
-You also need to use parameter `grant_type=client_credentials` as per OAuth2 specification. 
+You also need to use parameter `grant_type=client_credentials` as per OAuth2 specification.
 
 For example the POST invocation to retrieve service account can look like this: 
 
@@ -47,5 +51,3 @@ Pragma: no-cache
 ----    
 
 The retrieved access token can be refreshed or logged out by out-of-bound request. 
-
-See the example application `service-account` from the main Keycloak `demo` example. 

topics/clients/protocol-mappers.adoc

@@ -1,4 +1,5 @@
 [[_mappers]]
+
 = OIDC Token and SAML Assertion Mappings
 
 Applications that receive ID Tokens, Access Tokens, or SAML assertions may need or want different user metadata and roles.

topics/overview/concepts.adoc

@@ -45,6 +45,20 @@ consent::
 client templates::
   When a client is registered you need to enter in a bunch of configuration information about that client.  It is often useful to store a template
   of this to make create new clients easier.  {{book.project.name}} provides the concept of a client template for this.
+client role::
+  Clients can define roles that are specific to them.  This is basically a role namespace dedicated to the client.
+identity token::
+  A token that provides identity information about the user.  Part of the OpenID Connect specification.
+access token::
+  A token that can be provided as part of an HTTP request that grants access to the service being invoked on.  This is part of
+  the OpenID Connect and OAuth 2.0 specification.
+assertion::
+  Information about a user.  This usually pertains to an XML blob that is included in a SAML authentication response that
+  provided identity metadata about an authenticated user.
+service account::
+  Each client has a built in service account which allows them to obtain an access token.
+direct grant::
+  A way for a client to obtain an access token on behalf of a user via a REST invocation.
 protocol mappers::
   For each client you can tailor what claims and assertions are stored in the OIDC token or SAML assertion.  You do this per client by creating and configuring
   protocol mappers.

topics/sso-protocols/oidc.adoc

@@ -49,6 +49,7 @@ refresh protocol is important in the situation of a compromised system.  If acce
 vulnerable to a stolen token for the lifetime of the access token.  Future refresh token requests will fail if an admin
 has revoked access.  This makes things more secure and more scalable.
 
+[[_confidential-clients]]
 Another important aspect of this flow is the concept of a _public_ vs. a _confidential_ client.  _Confidential_ clients are required
 to provide a client secret when they exchange the temporary codes for tokens.  _Public_ clients are not required to provide this client secret.
 _Public_ clients are perfectly fine so long as HTTPS is strictly enforced and you are very strict about what redirect URIs are registered for the
@@ -79,7 +80,7 @@ the credentials of the user as well as the id of the client and the client's sec
 are sent within form parameters.  The HTTP response contains
 _identity_, _access_, and _refresh_ tokens.
 
-===== Client Credential Grant (Client Grants)
+===== Client Credentials Grant
 
 This is also used by REST clients, but instead of obtaining a token that works on behalf
 of an external user, a token is created based on the metadata and permissions of a service account that is associated with the client.