Merge pull request #44 from mposolda/master

KEYCLOAK-3666 Client Registration Policies docs

topics/client-registration.adoc

@@ -19,7 +19,8 @@ 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 bearer token, an initial access token or a registration access token.
+To invoke the Client Registration Services you usually need a token. The token can be a bearer token, an initial access token or a registration access token.
+There is an alternative to register new client without any token as well, but then you need to configure Client Registration Policies (see below).
 
 ==== Bearer Token
 
@@ -37,7 +38,8 @@ The recommended approach to registering new clients is by using initial access t
 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. 
+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
+`Client Registration` in the tabs displayed in the page. Then finally click on `Initial Access Tokens` sub-tab.
 
 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
@@ -159,3 +161,48 @@ client = reg.create(client);
 
 String registrationAccessToken = client.getRegistrationAccessToken();
 ----
+
+=== Client Registration Policies
+
+{{book.project.name}} currently supports 2 ways how can be new clients registered through Client Registration Service.
+
+* Authenticated requests - Request to register new client must contain either `Initial Access Token` or `Bearer Token` as mentioned above.
+
+* Anonymous requests - Request to register new client doesn't need to contain any token at all
+
+Anonymous client registration requests are very interesting and powerful feature, however you usually don't want that anyone is able to register new
+client without any limitations. Hence we have `Client Registration Policy SPI`, which provide a way to limit who can register new clients and under which conditions.
+
+In {{book.project.name}} admin console, you can click to `Client Registration` tab and then `Client Registration Policies` sub-tab. Here you will see what policies
+are configured by default for anonymous requests and what policies are configured for authenticated requests.
+
+NOTE: The anonymous requests (requests without any token) are allowed just for creating (registration) of new clients. So when you register
+new client through anonymous request, the response will contain Registration Access Token, which must be used for Read, Update or Delete request of particular client.
+However using this Registration Access Token from anonymous registration will be then subject to Anonymous Policy too! This means that for example request for update
+client also needs to come from Trusted Host if you have `Trusted Hosts` policy. Also for example it won't be allowed to disable `Consent Required` when updating client and
+when `Consent Required` policy is present etc.
+
+Currently we have these policy implementations:
+
+* Trusted Hosts Policy - You can configure list of trusted hosts and trusted domains. Request to Client Registration Service can be sent just from those hosts or domains.
+Request sent from some untrusted IP will be rejected. URLs of newly registered client must also use just those trusted hosts or domains. For example it won't be allowed
+to set `Redirect URI` of client pointing to some untrusted host. By default, there is not any whitelisted host, so anonymous client registration is de-facto disabled by default.
+
+* Consent Required Policy - Newly registered clients will have `Consent Allowed` switch enabled. So after successful authentication, user will always
+see consent screen when he needs to approve personal info and permissions (protocol mappers and roles). It means that client won't have access to any personal
+info or permission of user unless user approves it.
+
+* Protocol Mappers Policy - Allows to configure list of whitelisted protocol mapper implementations. New client can't be registered
+or updated if it contains some non-whitelisted protocol mapper. Note that this policy is used for authenticated requests as well, so
+even for authenticated request there are some limitations which protocol mappers can be used.
+
+* Client Template Policy - Allow to whitelist `Client Templates`, which can be used with newly registered or updated clients.
+There are no whitelisted templates by default.
+
+* Full Scope Policy - Newly registered clients will have `Full Scope Allowed` switch disabled. This means they won't have any scoped
+realm roles or client roles of other clients.
+
+* Max Clients Policy - Rejects registration if current number of clients in the realm is same or bigger than specified limit. It's 200 by default for anonymous registrations.
+
+* Client Disabled Policy - Newly registered client will be disabled. This means that admin needs to manually approve and enable all newly registered clients.
+This policy is not used by default even for anonymous registration.