From 6fb98c547ad71f528e7958923b970e9268dd127a Mon Sep 17 00:00:00 2001 From: mposolda Date: Thu, 30 Apr 2015 13:14:24 +0200 Subject: [PATCH] Docs fix for Application and OAuth client merge. Migration. Docs fix for direct access grants --- .../modules/MigrationFromOlderVersions.xml | 18 +++++++++++ .../reference/en/en-US/modules/Overview.xml | 31 ++++++++++--------- .../en/en-US/modules/access-types.xml | 8 ++--- .../en/en-US/modules/admin-rest-api.xml | 3 +- docbook/reference/en/en-US/modules/cors.xml | 6 ++-- .../en/en-US/modules/direct-access.xml | 24 +++++++------- docbook/reference/en/en-US/modules/roles.xml | 2 +- .../modules/security-vulnerabilities.xml | 6 ++-- 8 files changed, 59 insertions(+), 39 deletions(-) diff --git a/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml b/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml index f66c09d2ea..c35f746496 100755 --- a/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml +++ b/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml @@ -79,6 +79,24 @@
Version specific migration +
+ Migrating from 1.2.0.Beta1 to 1.2.0.RC1 + + Database changed + + 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. + + + + Application and OAuth client merge + + Application and OAuth clients are now merged into Clients. 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 Consent required + switch off and OAuth Clients will be converted into Clients with this switch on. + + +
Migrating from 1.1.0.Final to 1.2.0.Beta1 diff --git a/docbook/reference/en/en-US/modules/Overview.xml b/docbook/reference/en/en-US/modules/Overview.xml index 8a545d412a..3e42f1e7aa 100755 --- a/docbook/reference/en/en-US/modules/Overview.xml +++ b/docbook/reference/en/en-US/modules/Overview.xml @@ -82,7 +82,7 @@ Completely centrally managed user and role mapping metadata. Minimal configuration at the application side - 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. Account Management console that allows users to manage their own account, view their open sessions, reset passwords, etc. @@ -111,23 +111,24 @@ Key Concepts in Keycloak The core concept in Keycloak is a Realm. 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. - An application is a service that is secured by a realm. When a user browses an + A client 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. - An oauth client 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 Consent required 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.
@@ -156,13 +157,13 @@
Permission Scopes - 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.
diff --git a/docbook/reference/en/en-US/modules/access-types.xml b/docbook/reference/en/en-US/modules/access-types.xml index f478ceb3b8..ce6cf5d515 100755 --- a/docbook/reference/en/en-US/modules/access-types.xml +++ b/docbook/reference/en/en-US/modules/access-types.xml @@ -1,7 +1,7 @@ - Application and Client Access Types + Client Access Types - 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. @@ -43,8 +43,8 @@ direct access only - 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 Direct Access Grant + You would also see a "Direct Access Only" switch when creating the Client. + This switch is for clients that only use the Direct Access Grant protocol to obtain access tokens. diff --git a/docbook/reference/en/en-US/modules/admin-rest-api.xml b/docbook/reference/en/en-US/modules/admin-rest-api.xml index 56d5ccd63e..93e542387f 100755 --- a/docbook/reference/en/en-US/modules/admin-rest-api.xml +++ b/docbook/reference/en/en-US/modules/admin-rest-api.xml @@ -12,6 +12,7 @@ There are a number of examples that come with the keycloak distribution that show you how to invoke on this REST API. examples/preconfigured-demo/admin-access-app shows you how to access this api from java. - examples/cors/angular-product-app shows you how to invoke on it from Javascript. + examples/cors/angular-product-app shows you how to invoke on it from Javascript. Finally there is example in + example/admin-client, which contains example for Admin client, that can be used to invoke REST endpoints easily as Java methods. \ No newline at end of file diff --git a/docbook/reference/en/en-US/modules/cors.xml b/docbook/reference/en/en-US/modules/cors.xml index f04c535fad..99ced70207 100755 --- a/docbook/reference/en/en-US/modules/cors.xml +++ b/docbook/reference/en/en-US/modules/cors.xml @@ -8,11 +8,11 @@ against XSS and other Javascript-based attacks. Keycloak has support for validated CORS requests. - 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 Origin header. For example http://example.com is what you must specify to allow CORS requests from example.com. 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 Origin header against the allowed origins embedded in the token. If there is no match, then the request is denied. diff --git a/docbook/reference/en/en-US/modules/direct-access.xml b/docbook/reference/en/en-US/modules/direct-access.xml index ee67ced9c2..b21f82b15a 100755 --- a/docbook/reference/en/en-US/modules/direct-access.xml +++ b/docbook/reference/en/en-US/modules/direct-access.xml @@ -5,7 +5,7 @@ (See Resource Owner Password Credentials Grant 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. @@ -24,21 +24,21 @@ - The REST URL to invoke on is /{keycloak-root}/realms/{realm-name}/tokens/grants/access. + The REST URL to invoke on is /{keycloak-root}/realms/{realm-name}/protocol/openid-connect/token. 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 "public" or "confidential", 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 "public" or "confidential", you may also have to pass along + it's client secret as well. Finally you need to pass "grant_type" parameter with value "password" . - 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: + username=bburke&password=geheim&client_id=customer-portal&grant_type=password]]> The response would be this standard JSON document from the OAuth 2.0 specification. - For confidential applications or oauth client's, you must create a Basic Auth Authorization + For confidential client's, you must create a Basic Auth Authorization header that contains the client_id and client secret. And pass in the form parameters for username and for each user credential. For example: + username=bburke&password=geheim&grant_type=password]]> diff --git a/docbook/reference/en/en-US/modules/roles.xml b/docbook/reference/en/en-US/modules/roles.xml index 1dcb89f26c..97e80d5a7a 100755 --- a/docbook/reference/en/en-US/modules/roles.xml +++ b/docbook/reference/en/en-US/modules/roles.xml @@ -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. Composite roles can be associated with any type of role Realm or Application. In the admin console simple diff --git a/docbook/reference/en/en-US/modules/security-vulnerabilities.xml b/docbook/reference/en/en-US/modules/security-vulnerabilities.xml index 0c4bee34d5..7107fb7b6f 100755 --- a/docbook/reference/en/en-US/modules/security-vulnerabilities.xml +++ b/docbook/reference/en/en-US/modules/security-vulnerabilities.xml @@ -168,9 +168,9 @@
Limiting Scope - Using the Scope 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 Scope 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.