libre.sh/keycloak-scim
4
0
Fork 0
Code Issues 15 Pull requests Releases 1 Activity Actions

KEYCLOAK-9378 server admin guide ch12 changes

Browse source
This commit is contained in:
Matthew Helmke 2019-01-18 13:17:57 -06:00 committed by Stian Thorgersen
parent 3b2b08eb28
commit dff320c166
15 changed files with 53 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
server_admin/topics/identity-broker/configuration.adoc
View file

@ -27,7 +27,7 @@ image:{project_images}/identity-provider-login-page.png[]
Social::
Social providers allow you to enable social authentication in your realm.
{project_name} makes it easy to let users log in to your application using an existing account with a social network.
Currently Facebook, Google, Twitter, GitHub, LinkedIn, Microsoft, and StackOverflow are supported with more planned for the future.
Currently supported providers include: Twitter, Facebook, Google, LinkedIn, Instagram, Microsoft, PayPal, Openshift v3, GitHub, GitLab, Bitbucket, and Stack Overflow.
Protocol-based::
Protocol-based providers are those that rely on a specific protocol in order to authenticate and authorize users.
@ -36,7 +36,7 @@ Protocol-based::
It makes it easy to configure and broker any identity provider based on these open standards.
Although each type of identity provider has its own configuration options, all of them share some very common configuration.
Regardless the identity provider you are creating, you'll see the following configuration options available:
Regardless of which identity provider you are creating, you'll see the following configuration options available:
.Common Configuration
[cols="1,1", options="header"]
@ -44,18 +44,18 @@ Regardless the identity provider you are creating, you'll see the following conf
|Configuration|Description
|Alias
|The alias is an unique identifier for an identity provider. It is used to reference an identity provider internally.
|The alias is a unique identifier for an identity provider. It is used to reference an identity provider internally.
Some protocols such as OpenID Connect require a redirect URI or callback url in order to communicate with an identity provider.
In this case, the alias is used to build the redirect URI.
Every single identity provider must have an alias. Examples are facebook, google, idp.acme.com, etc.
Every single identity provider must have an alias. Examples are `facebook`, `google`, `idp.acme.com`, etc.
|Enabled
|Turn the provider on/off
|Turn the provider on/off.
|Hide On Login Page
|Hide on Login Page
|When this switch is on, this provider will not be shown as a login option on the login page. Clients can still request to use this provider by using the 'kc_idp_hint' parameter in the URL they use to request a login.
|Link Only
|Account Linking Only
|When this switch is on, this provider cannot be used to login users and will not be shown as an option on the login page. Existing accounts can still be linked with this provider though.
@ -64,14 +64,14 @@ Regardless the identity provider you are creating, you'll see the following conf
|Stored Tokens Readable
|Whether or not users are allowed to retrieve the stored identity provider token. This also applies to the _broker_ client-level
role _read token_
role _read token_.
|Trust email
|Trust Email
|If the identity provider supplies an email address this email address will be trusted. If the realm required email validation,
users that log in from this IDP will not have to go through the email verification process.
|GUI order
|The order number that sorts how the available IDPs are listed on the {project_name} login page.
|GUI Order
|The order number that sorts how the available IDPs are listed on the login page.
|First Login Flow
|This is the authentication flow that will be triggered for users that log into {project_name} through this IDP

2
server_admin/topics/identity-broker/default-provider.adoc
View file

@ -2,7 +2,7 @@
=== Default Identity Provider
It's possible to automatically redirect to a identity provider instead of displaying the login form. To enable this go to `Authentication` select the `Browser` flow. Then click on config for the `Identity Provider Redirector` authenticator. Set `Default Identity Provider` to the alias of the identity provider you want to automatically redirect users to.
It is possible to automatically redirect to a identity provider instead of displaying the login form. To enable this go to the `Authentication` page in the administration console and select the `Browser` flow. Then click on config for the `Identity Provider Redirector` authenticator. Set `Default Identity Provider` to the alias of the identity provider you want to automatically redirect users to.
If the configured default identity provider is not found the login form will be displayed instead.

30
server_admin/topics/identity-broker/oidc.adoc
View file

@ -18,10 +18,10 @@ You must define the OpenID Connect configuration options as well. They basicall
|Configuration|Description
|Authorization URL
|Authorization URL endpoint required by the OIDC protocol
|Authorization URL endpoint required by the OIDC protocol.
|Token URL
|Token URL endpoint required by the OIDC protocol
|Token URL endpoint required by the OIDC protocol.
|Logout URL
|Logout URL endpoint defined in the OIDC protocol. This value is optional.
@ -34,8 +34,8 @@ You must define the OpenID Connect configuration options as well. They basicall
|User Info URL endpoint defined by the OIDC protocol. This is an endpoint from which user profile information can be downloaded.
|Client ID
|This realm will act as an OIDC client to the external federation IDP you are configuring here. Your realm will need a OIDC client ID when using the Authorization Code Flow
to interact with the external IDP
|This realm will act as an OIDC client to the external IDP. Your realm will need an OIDC client ID when using the Authorization Code Flow
to interact with the external IDP.
|Client Secret
|This realm will need a client secret to use when using the Authorization Code Flow.
@ -44,28 +44,28 @@ You must define the OpenID Connect configuration options as well. They basicall
|Responses from the IDP may contain an issuer claim. This config value is optional. If specified, this claim will be validated against the value you provide.
|Default Scopes
|Space-separated list of OIDC scopes to send with the authentication request. The default is `openid`
|Space-separated list of OIDC scopes to send with the authentication request. The default is `openid`.
|Prompt
|Another optional switch. This is the prompt parameter defined by the OIDC specification. Through it you can force re-authentication and other options. See the specification for
more details
more details.
|Validate Signatures
|Another optional switch. This is to specify if {project_name} will verify the signatures on the external ID Token signed by this Identity provider. If this is on,
the {project_name} will need to know the public key of the external OIDC identity provider. See below for how to setup it.
WARNING: For the performance purposes, {project_name} caches the public key of the external OIDC identity provider. If you think that private key of your Identity provider
|Another optional switch. This is to specify if {project_name} will verify the signatures on the external ID Token signed by this identity provider. If this is on,
the {project_name} will need to know the public key of the external OIDC identity provider. See below for how to set it up.
WARNING: For the performance purposes, {project_name} caches the public key of the external OIDC identity provider. If you think that private key of your identity provider
was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See
<<_clear-cache, Clearing the cache>> section for more details.
|Use JWKS URL
|Applicable if `Validate Signatures` is on. If the switch is on, then identity provider public keys will be downloaded from given JWKS URL.
This allows great flexibility because new keys will be always re-downloaded again when identity provider generates new keypair. If the switch is off,
then public key (or certificate) from the {project_name} DB is used, so when identity provider keypair changes, you always need to import new key to the {project_name} DB as well.
|Applicable if `Validate Signatures` is on. If the switch is on, then identity provider public keys will be downloaded from given JWKS URL.
This allows great flexibility because new keys will be always re-downloaded when the identity provider generates new keypair. If the switch is off,
then public key (or certificate) from the {project_name} DB is used, so whenever the identity provider keypair changes, you will always need to import the new key to the {project_name} DB as well.
|JWKS URL
|URL where identity provider keys in JWK format are stored. See https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK specification] for more details.
If you use external {project_name} identity provider, then you can use URL like http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs assuming your brokered
{project_name} is running on http://broker-keycloak:8180 and it's realm is `test` .
|URL where the identity provider JWK keys are stored. See the https://self-issued.info/docs/draft-ietf-jose-json-web-key.html[JWK specification] for more details.
If you use an external {project_name} as an identity provider, then you can use URL like http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs assuming your brokered
{project_name} is running on http://broker-keycloak:8180 and it's realm is `test`.
|Validating Public Key
|Applicable if `Use JWKS URL` is off. Here is the public key in PEM format that must be used to verify external IDP signatures.

12
server_admin/topics/identity-broker/overview.adoc
View file

@ -5,7 +5,7 @@
When using {project_name} as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm.
Instead, they are presented with a list of identity providers from which they can authenticate.
You can also configure a default broker. In this case the user will not be given a choice, but instead be redirected directly to the parent broker.
You can also configure a default identity provider. In this case the user will not be given a choice, but will instead be redirected directly to the default provider.
The following diagram demonstrates the steps involved when using {project_name} to broker an external identity provider:
@ -14,12 +14,12 @@ image:images/identity_broker_flow.png[]
. User is not authenticated and requests a protected resource in a client application.
. The client applications redirects the user to {project_name} to authenticate.
. At this point the user is presented with the login page where there is a list of identity providers supported by a realm.
. At this point the user is presented with the login page where there is a list of identity providers configured in a realm.
. User selects one of the identity providers by clicking on its respective button or link.
. {project_name} issues an authentication request to the target identity provider asking for authentication and the user
is redirected to the login page of the identity provider.
The connection properties and other configuration options for the identity provider were previously set by the administrator in the Admin Console.
. User provides his credentials or consent in order to authenticate in the identity provider.
. User provides his credentials or consent in order to authenticate with the identity provider.
. Upon a successful authentication by the identity provider, the user is redirected back to {project_name} with an authentication response.
Usually this response contains a security token that will be used by {project_name} to trust the authentication performed by the identity provider
and retrieve information about the user.
@ -27,9 +27,9 @@ image:images/identity_broker_flow.png[]
If valid, it will import and create a new user or just skip that if the user already exists.
If it is a new user, {project_name} may ask the identity provider for information about the user if that info doesn't already exist in the token.
This is what we call _identity federation_.
If the user already exists {project_name} may ask him to link the identity returned from the identity provider with his existing account.
If the user already exists {project_name} may ask him to link the identity returned from the identity provider with the existing account.
We call this process _account linking_.
What exactly is done is configurable and can be specified by setup of <<_identity_broker_first_login,First Login Flow>> . At the end of this step, {project_name} authenticates the user and issues its own token in order to access the requested resource in the service provider.
What exactly is done is configurable and can be specified by setup of <<_identity_broker_first_login,First Login Flow>>. At the end of this step, {project_name} authenticates the user and issues its own token in order to access the requested resource in the service provider.
. Once the user is locally authenticated, {project_name} redirects the user to the service provider by sending the token previously issued during the local authentication.
. The service provider receives the token from {project_name} and allows access to the protected resource.
@ -39,7 +39,7 @@ Or you can tell {project_name} to force the user to provide additional informati
NOTE: Different protocols may require different authentication flows.
At this moment, all the identity providers supported by {project_name} use a flow just like described above.
However, despite the protocol in use, user experience should be pretty much the same.
However, regardless of the protocol in use, user experience should be pretty much the same.
As you may notice, at the end of the authentication process {project_name} will always issue its own token to client applications.
What this means is that client applications are completely decoupled from external identity providers.

8
server_admin/topics/identity-broker/social/bitbucket.adoc
View file

@ -1,6 +1,6 @@
==== Bitbucket
There are a number of steps you have to complete to be able to login to Bitbucket.
There are a number of steps you have to complete to be able to enable login with Bitbucket.
First, open the `Identity Providers` left menu item and select `Bitbucket` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
@ -9,7 +9,7 @@ image:{project_images}/bitbucket-add-identity-provider.png[]
Before you can click `Save`, you must obtain a `Client ID` and `Client Secret` from Bitbucket.
NOTE: You will the `Redirect URI` from this page in a later step, which you will provide to Bitbucket when you register {project_name} as a client there.
NOTE: You will use the `Redirect URI` from this page in a later step, which you will provide to Bitbucket when you register {project_name} as a client there.
.Add a New App
To enable login with Bitbucket you must first register an application project in
@ -24,7 +24,7 @@ Click the `Add consumer` button.
.Register App
image:images/bitbucket-register-app.png[]
Copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the `Authorization callback URL` field on the Bitbucket `Register a new OAuth application` page.
Copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the Callback URL field on the Bitbucket Add OAuth Consumer page.
On the same page, mark the `Email` and `Read` boxes under `Account` to allow your application to read user email.
@ -33,4 +33,4 @@ image:images/bitbucket-app-page.png[]
When you are done registering, click `Save`. This will open the application management page in Bitbucket. Find the client ID and secret from this page so you can enter them into the {project_name} `Add identity provider` page.
+
+To finish, return to {project_name} and enter them. Click `Save`.
+Find the values of `client ID` and `secret` on this page and enter them into the {project_name} Add Identity Provider page. Click `Save`.

2
server_admin/topics/identity-broker/social/facebook.adoc
View file

@ -1,7 +1,7 @@
==== Facebook
There are a number of steps you have to complete to be able to login to Facebook. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with Facebook. First, go to the `Identity Providers` left menu item
and select `Facebook` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider

2
server_admin/topics/identity-broker/social/github.adoc
View file

@ -1,7 +1,7 @@
==== GitHub
There are a number of steps you have to complete to be able to login to GitHub. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with GitHub. First, go to the `Identity Providers` left menu item
and select `GitHub` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider

8
server_admin/topics/identity-broker/social/gitlab.adoc
View file

@ -1,7 +1,7 @@
==== GitLab
There are a number of steps you have to complete to be able to login to GitLab.
There are a number of steps you have to complete to be able to enable login with GitLab.
First, go to the `Identity Providers` left menu item and select `GitLab` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
@ -10,9 +10,9 @@ image:{project_images}/gitlab-add-identity-provider.png[]
Before you can click `Save`, you must obtain a `Client ID` and `Client Secret` from GitLab.
NOTE: You will the `Redirect URI` from this page in a later step, which you will provide to GitLab when you register {project_name} as a client there.
NOTE: You will the use `Redirect URI` from this page in a later step, which you will provide to GitLab when you register {project_name} as a client there.
To enable login with GitLab you first have to register an application project in
To enable login with GitLab you first have to register an application in
https://docs.gitlab.com/ee/integration/oauth_provider.html[GitLab as OAuth2 authentication service provider].
NOTE: GitLab often changes the look and feel of application registration, so what you see on the GitLab site may differ. If in doubt, see the GitLab documentation.
@ -20,7 +20,7 @@ NOTE: GitLab often changes the look and feel of application registration, so wha
.Add a New App
image:images/gitlab-developer-applications.png[]
Copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the `Authorization callback URL` field on the GitLab `Register a new OAuth application` page.
Copy the `Redirect URI` from the {project_name} `Add Identity Provider` page and enter it into the Redirect URI field on the GitLab Add new application page.
.GitLab App Page
image:images/gitlab-app-page.png[]

4
server_admin/topics/identity-broker/social/google.adoc
View file

@ -1,7 +1,7 @@
==== Google
There are a number of steps you have to complete to be able to login to Google. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with Google. First, go to the `Identity Providers` left menu item
and select `Google` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider
@ -12,7 +12,7 @@ page is the `Redirect URI`. You'll have to provide that to Google when you regi
copy this URI to your clipboard.
To enable login with Google you first have to create a project and a client in the https://console.cloud.google.com/project[Google Developer Console].
Then you need to copy the client id and secret into the {project_name} Admin Console.
Then you need to copy the client ID and secret into the {project_name} Admin Console.
NOTE: Google often changes the look and feel of the Google Developer Console, so these directions might not always be up to date and the
configuration steps might be slightly different.

2
server_admin/topics/identity-broker/social/linked-in.adoc
View file

@ -1,7 +1,7 @@
==== LinkedIn
There are a number of steps you have to complete to be able to login to LinkedIn. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with LinkedIn. First, go to the `Identity Providers` left menu item
and select `LinkedIn` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider

2
server_admin/topics/identity-broker/social/microsoft.adoc
View file

@ -1,7 +1,7 @@
==== Microsoft
There are a number of steps you have to complete to be able to login to Microsoft. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with Microsoft. First, go to the `Identity Providers` left menu item
and select `Microsoft` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider

2
server_admin/topics/identity-broker/social/openshift.adoc
View file

@ -3,7 +3,7 @@
NOTE: OpenShift Online is currently in the developer preview mode. This documentation has been based on on-premise installations and local `minishift` development environment.
There are a just a few steps you have to complete to be able to login to OpenShift. First, go to the `Identity Providers` left menu item
There are a just a few steps you have to complete to be able to enable login with OpenShift. First, go to the `Identity Providers` left menu item
and select `OpenShift` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider

2
server_admin/topics/identity-broker/social/paypal.adoc
View file

@ -1,7 +1,7 @@
==== PayPal
There are a number of steps you have to complete to be able to login to PayPal. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with PayPal. First, go to the `Identity Providers` left menu item
and select `PayPal` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider

4
server_admin/topics/identity-broker/social/stack-overflow.adoc
View file

@ -1,14 +1,14 @@
==== StackOverflow
There are a number of steps you have to complete to be able to login to StackOverflow. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with StackOverflow. First, go to the `Identity Providers` left menu item
and select `StackOverflow` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider
image:{project_images}/stack-overflow-add-identity-provider.png[]
To enable login with StackOverflow you first have to register an OAuth application on https://stackapps.com/[StackApps].
Go to https://stackapps.com/apps/oauth/register[registering your application on Stack Apps] url and login.
Go to https://stackapps.com/apps/oauth/register[registering your application on Stack Apps] URL and login.
NOTE: StackOverflow often changes the look and feel of application registration, so these directions might not always be up to date and the
configuration steps might be slightly different.

5
server_admin/topics/identity-broker/social/twitter.adoc
View file

@ -1,7 +1,7 @@
==== Twitter
There are a number of steps you have to complete to be able to login to Twitter. First, go to the `Identity Providers` left menu item
There are a number of steps you have to complete to be able to enable login with Twitter. First, go to the `Identity Providers` left menu item
and select `Twitter` from the `Add provider` drop down list. This will bring you to the `Add identity provider` page.
.Add Identity Provider
@ -26,8 +26,7 @@ image:images/twitter-app-create.png[]
Enter in a Name and Description. The Website can be anything, but cannot have a `localhost` address. For the
`Callback URL` you must copy the `Redirect URI` from the {project_name} `Add Identity Provider` page.
WARNING: You cannot use `localhost` in the `Callback URL`. Instead replace it with `127.0.0.1` if you are trying to
testdrive Twitter login on your laptop.
WARNING: You cannot use `localhost` in the `Callback URL`. Instead replace it with `127.0.0.1` if you are trying to test drive Twitter login on your laptop.
After clicking save you will be brought to the `Details` page.