Docs fix for Application and OAuth client merge. Migration. Docs fix for direct access grants
This commit is contained in:
mposolda
parent
f1bff01999
commit
6fb98c547a
8 changed files with 59 additions and 39 deletions
|
|
@ -79,6 +79,24 @@
|
|||
|
||||
<section>
|
||||
<title>Version specific migration</title>
|
||||
<section>
|
||||
<title>Migrating from 1.2.0.Beta1 to 1.2.0.RC1</title>
|
||||
<simplesect>
|
||||
<title>Database changed</title>
|
||||
<para>
|
||||
This release contains again a number of changes to the database. The biggest one is Application and OAuth client merge.
|
||||
Remember to backup your database prior to upgrading.
|
||||
</para>
|
||||
</simplesect>
|
||||
<simplesect>
|
||||
<title>Application and OAuth client merge</title>
|
||||
<para>
|
||||
Application and OAuth clients are now merged into <literal>Clients</literal>. The UI of admin console is updated and database as well.
|
||||
Your data from database should be automatically updated. The previously set Applications will be converted into Clients with <literal>Consent required</literal>
|
||||
switch off and OAuth Clients will be converted into Clients with this switch on.
|
||||
</para>
|
||||
</simplesect>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from 1.1.0.Final to 1.2.0.Beta1</title>
|
||||
<simplesect>
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@
|
|||
Completely centrally managed user and role mapping metadata. Minimal configuration at the application side
|
||||
</listitem>
|
||||
<listitem>
|
||||
Admin Console for managing users, roles, role mappings, applications, user sessions, allowed CORS web origins, and OAuth clients.
|
||||
Admin Console for managing users, roles, role mappings, clients, user sessions and allowed CORS web origins.
|
||||
</listitem>
|
||||
<listitem>
|
||||
Account Management console that allows users to manage their own account, view their open sessions, reset passwords, etc.
|
||||
|
|
@ -111,23 +111,24 @@
|
|||
<title>Key Concepts in Keycloak</title>
|
||||
<para>
|
||||
The core concept in Keycloak is a <emphasis>Realm</emphasis>. A realm secures and manages security metadata
|
||||
for a set of users, applications, and registered oauth clients. Users can be created within a specific realm
|
||||
for a set of users and registered clients. Users can be created within a specific realm
|
||||
within the Administration console. Roles (permission types) can be defined at the realm level and you can also
|
||||
set up user role mappings to assign these permissions to specific users.
|
||||
</para>
|
||||
<para>
|
||||
An <emphasis>application</emphasis> is a service that is secured by a realm. When a user browses an
|
||||
A <emphasis>client</emphasis> is a service that is secured by a realm. You will often use Client for every Application secured by Keycloak. When a user browses an
|
||||
application's web site, the application can redirect the user agent to the Keycloak Server and request a login.
|
||||
Once a user is logged in, they can visit any other application managed by the realm and not have to re-enter
|
||||
credentials. This also hold true for logging out. Roles can also be defined at the application level and
|
||||
assigned to specific users. Depending on the application type, you may also be able to view and manage
|
||||
Once a user is logged in, they can visit any other client (application) managed by the realm and not have to re-enter
|
||||
credentials. This also hold true for logging out. Roles can also be defined at the client level and
|
||||
assigned to specific users. Depending on the client type, you may also be able to view and manage
|
||||
user sessions from the administration console.
|
||||
</para>
|
||||
<para>
|
||||
An <emphasis>oauth client</emphasis> is similar to an application in that it can request something like a login
|
||||
when a user visits the site of the oauth client. The difference is that oauth clients are not immediately granted
|
||||
In admin console there is switch <emphasis>Consent required</emphasis> specified when creating/editing client. When on, the client is not immediately granted
|
||||
all permissions of the user. In addition to requesting the login credentials of the user, the Keycloak Server
|
||||
will also display a grant page asking the user if it is ok to grant allowed permissions to the oauth client.
|
||||
will also display a grant page asking the user if it is ok to grant allowed permissions to the client. The granted consents are saved
|
||||
and every user can see his granted consents in Account Management UI and he can also revoke them for particular client. Also admin can see and revoke the grants
|
||||
of particular user in Keycloak Admin Console UI.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
|
|
@ -156,13 +157,13 @@
|
|||
<section>
|
||||
<title>Permission Scopes</title>
|
||||
<para>
|
||||
Each application and oauth client are configured with a set of permission scopes. These are a set
|
||||
of roles that an application or oauth client is allowed to ask permission for. Access tokens are always
|
||||
granted at the request of a specific application or oauth client. This also holds true for SSO. As you visit
|
||||
Each client is configured with a set of permission scopes. These are a set
|
||||
of roles that a client is allowed to ask permission for. Access tokens are always
|
||||
granted at the request of a specific client. This also holds true for SSO. As you visit
|
||||
different sites, the application will redirect back to the Keycloak Server via the OAuth 2.0 protocol to obtain an access
|
||||
token specific to that application. The role mappings contained within the token are the intersection
|
||||
between the set of user role mappings and the permission scope of the application/oauth client. So,
|
||||
access tokens are tailor made for each application/oauth client and contain only the information required
|
||||
token specific to that application (client). The role mappings contained within the token are the intersection
|
||||
between the set of user role mappings and the permission scope of the client. So,
|
||||
access tokens are tailor made for each client and contain only the information required
|
||||
for by them.
|
||||
</para>
|
||||
</section>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<chapter id="access-types">
|
||||
<title>Application and Client Access Types</title>
|
||||
<title>Client Access Types</title>
|
||||
<para>
|
||||
When you create an Application or OAuth Client you may be wondering what the "Access Types" are.
|
||||
When you create a Client in admin console you may be wondering what the "Access Types" are.
|
||||
</para>
|
||||
<para>
|
||||
<variablelist>
|
||||
|
|
@ -43,8 +43,8 @@
|
|||
<term>direct access only</term>
|
||||
<listitem>
|
||||
<para>
|
||||
For OAuth clients, you would also see a "Direct Access Only" switch when creating the OAuth Client.
|
||||
This switch is for oauth clients that only use the <link linkend='direct-access-grants'>Direct Access Grant</link>
|
||||
You would also see a "Direct Access Only" switch when creating the Client.
|
||||
This switch is for clients that only use the <link linkend='direct-access-grants'>Direct Access Grant</link>
|
||||
protocol to obtain access tokens.
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
|
|||
|
|
@ -12,6 +12,7 @@
|
|||
<para>
|
||||
There are a number of examples that come with the keycloak distribution that show you how to invoke on this REST API.
|
||||
<literal>examples/preconfigured-demo/admin-access-app</literal> shows you how to access this api from java.
|
||||
<literal>examples/cors/angular-product-app</literal> shows you how to invoke on it from Javascript.
|
||||
<literal>examples/cors/angular-product-app</literal> shows you how to invoke on it from Javascript. Finally there is example in
|
||||
<literal>example/admin-client</literal>, which contains example for Admin client, that can be used to invoke REST endpoints easily as Java methods.
|
||||
</para>
|
||||
</chapter>
|
||||
|
|
@ -8,11 +8,11 @@
|
|||
against XSS and other Javascript-based attacks. Keycloak has support for validated CORS requests.
|
||||
</para>
|
||||
<para>
|
||||
Keycloak's CORS support is configured per application and oauth client. You specify the allowed origins
|
||||
in the application's or oauth client's configuration page in the admin console. You can add as many you want. The value
|
||||
Keycloak's CORS support is configured per client. You specify the allowed origins
|
||||
in the client's configuration page in the admin console. You can add as many you want. The value
|
||||
must be what the browser would send as a value in the <literal>Origin</literal> header. For example <literal>http://example.com</literal>
|
||||
is what you must specify to allow CORS requests from <literal>example.com</literal>. When an access token is
|
||||
created for the application or OAuth client, these allowed origins are embedded within the token. On authenticated
|
||||
created for the client, these allowed origins are embedded within the token. On authenticated
|
||||
CORS requests, your application's Keycloak adapter will handle the CORS protocol and validate the <literal>Origin</literal>
|
||||
header against the allowed origins embedded in the token. If there is no match, then the request is denied.
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
(See <ulink url="http://tools.ietf.org/html/rfc6749#section-4.3">Resource Owner Password Credentials Grant</ulink>
|
||||
from OAuth 2.0 spec). To use it, Direct Access Grants must be allowed by your realm. This is a configuration switch
|
||||
in the admin console under Settings->General, specifically the "Direct Grant API" switch. You must also have
|
||||
registered a valid OAuth Client or Application to use as the "client_id" for this grant request.
|
||||
registered a valid Client to use as the "client_id" for this grant request.
|
||||
</para>
|
||||
<warning>
|
||||
<para>
|
||||
|
|
@ -24,21 +24,21 @@
|
|||
|
||||
|
||||
<para>
|
||||
The REST URL to invoke on is <literal>/{keycloak-root}/realms/{realm-name}/tokens/grants/access</literal>.
|
||||
The REST URL to invoke on is <literal>/{keycloak-root}/realms/{realm-name}/protocol/openid-connect/token</literal>.
|
||||
Invoking on this URL is a POST request and requires you to post the username and credentials of the user you want
|
||||
an access token for. You must also pass along the "client_id" of the application or oauth client you are creating
|
||||
an access token for. This "client_id" is the application or oauth client name (not it's id!). Depending on
|
||||
whether your application/oauth client is <link linkend='access-types'>"public" or "confidential"</link>, you may also have to pass along
|
||||
it's client secret as well.
|
||||
an access token for. You must also pass along the "client_id" of the client you are creating
|
||||
an access token for. This "client_id" is the Client Id specified in admin console (not it's id from DB!). Depending on
|
||||
whether your client is <link linkend='access-types'>"public" or "confidential"</link>, you may also have to pass along
|
||||
it's client secret as well. Finally you need to pass "grant_type" parameter with value "password" .
|
||||
</para>
|
||||
<para>
|
||||
For public applications or oauth client's, the POST invocation requires form parameters that contain the username,
|
||||
For public client's, the POST invocation requires form parameters that contain the username,
|
||||
credentials, and client_id of your application. For example:
|
||||
<programlisting><![CDATA[
|
||||
POST /auth/realms/demo/tokens/grants/access
|
||||
POST /auth/realms/demo/protocol/openid-connect/token
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
username=bburke&password=geheim&client_id=customer-portal]]>
|
||||
username=bburke&password=geheim&client_id=customer-portal&grant_type=password]]>
|
||||
</programlisting>
|
||||
The response would be this <ulink url="http://tools.ietf.org/html/rfc6749#section-4.3.3">standard JSON document</ulink> from the OAuth 2.0 specification.
|
||||
<programlisting><![CDATA[
|
||||
|
|
@ -58,15 +58,15 @@ Pragma: no-cache
|
|||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
For confidential applications or oauth client's, you must create a Basic Auth <literal>Authorization</literal>
|
||||
For confidential client's, you must create a Basic Auth <literal>Authorization</literal>
|
||||
header that contains the client_id and client secret. And pass in the form parameters for username and for
|
||||
each user credential. For example:
|
||||
<programlisting><![CDATA[
|
||||
POST /auth/realms/demo/tokens/grants/access
|
||||
POST /auth/realms/demo/protocol/openid-connect/token
|
||||
Authorization: Basic atasdf023l2312023
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
username=bburke&password=geheim]]>
|
||||
username=bburke&password=geheim&grant_type=password]]>
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@
|
|||
When a composite role is mapped to the user, the user gains the permission of that role, plus any other role the
|
||||
composite is associated with. This association is dynamic. So, if you add or remove an associated role from
|
||||
the composite, then all users that are mapped to the composite role will automatically have those permissions
|
||||
added or removed. Composites can also be used to define Application or OAuth Client scopes.
|
||||
added or removed. Composites can also be used to define Client scopes.
|
||||
</para>
|
||||
<para>
|
||||
Composite roles can be associated with any type of role Realm or Application. In the admin console simple
|
||||
|
|
|
|||
|
|
@ -168,9 +168,9 @@
|
|||
<section>
|
||||
<title>Limiting Scope</title>
|
||||
<para>
|
||||
Using the <literal>Scope</literal> menu in the admin console for oauth clients or applications, you can control
|
||||
exactly which role mappings will be included within the token sent back to the client or application. This
|
||||
allows you to limit the scope of permissions given to the application or client which is great if the client isn't
|
||||
Using the <literal>Scope</literal> menu in the admin console for clients, you can control
|
||||
exactly which role mappings will be included within the token sent back to the client application. This
|
||||
allows you to limit the scope of permissions given to the client which is great if the client isn't
|
||||
very trusted and is known to not being very careful with its tokens.
|
||||
</para>
|
||||
</section>
|
||||
|
|
|
|||
Loading…
Reference in a new issue