Merge remote-tracking branch 'upstream/master'
This commit is contained in:
Bill Burke committed
commit
742f162cfc
107 files changed
+1803
-395
No files matched your search
@@ -211,7 +211,7 @@
|
||||
<para>
|
||||
Social providers allows you to enable social authentication to your realm.
|
||||
Keycloak 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 and StackOverflow are supported with more planned for the future.
|
||||
Currently Facebook, Google, Twitter, GitHub, LinkedIn, Microsoft and StackOverflow are supported with more planned for the future.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@@ -357,7 +357,7 @@
|
||||
So is trying to remember yet another username and password combination.
|
||||
Social identity providers makes it easy for users to register on your realm and quickly sign in using a social network.
|
||||
Keycloak provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter,
|
||||
Github, LinkedId and StackOverflow.
|
||||
Github, LinkedId, Microsoft and StackOverflow.
|
||||
</para>
|
||||
|
||||
<section>
|
||||
@@ -855,6 +855,95 @@
|
||||
</tgroup>
|
||||
</table>
|
||||
</section>
|
||||
<section>
|
||||
<title>Microsoft</title>
|
||||
<para>
|
||||
To enable login with Microsoft account you first have to register an OAuth application on
|
||||
<ulink url="https://account.live.com/developers/applications/index">Microsoft account Developer Center</ulink>. Then you need to copy the client id and secret into the Keycloak Admin Console.
|
||||
</para>
|
||||
<para>
|
||||
Let's see first how to create an application with Microsoft.
|
||||
</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Go to <ulink url="https://account.live.com/developers/applications/create">create new application on Microsoft account Developer Center</ulink> url and login here.
|
||||
Use any value for <literal>Application Name</literal>, <literal>Application Logo</literal> and <literal>URLs</literal> you want.
|
||||
In <literal>API Settings</literal> set <literal>Target Domain</literal> to the domain where your Keycloak instance runs.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Copy <literal>Client Id</literal> and <literal>Client Secret</literal> from <literal>App Settings</literal> page.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<para>
|
||||
Now that you have the client id and secret you can proceed with the creation of a Microsoft Identity Provider in Keycloak. As follows:
|
||||
</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Select the <literal>Microsoft</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provided.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Copy the client id and client secret to their corresponding fields in the Keycloak Admin Console. Click <literal>Save</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<para>
|
||||
Once you create the identity provider in Keycloak, you must update your Microsoft application with the redirect url that was
|
||||
generated to your identity provider.
|
||||
</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Open the Microsoft account Developer Center and select <literal>API Settings</literal> of your application. In <literal>Redirect URLs</literal>
|
||||
insert the redirect uri created by Keycloak. The redirect uri
|
||||
usually have the following format: <literal>http://{host}:{port}/auth/realms/{realm}/broker/microsoft/endpoint</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<note>
|
||||
<para>
|
||||
You can always get the redirect url for a specific identity provider from the table presented when you
|
||||
click on the 'Identity Provider' tab in <emphasis>Realm > Settings</emphasis>.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
That is it! This pretty much what you need to do in order to setup this identity provider.
|
||||
</para>
|
||||
<para>
|
||||
The table below lists some additional configuration options you may use when configuring this provider.
|
||||
</para>
|
||||
<table>
|
||||
<title>Configuration Options</title>
|
||||
<tgroup align="left" cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>
|
||||
Configuration
|
||||
</entry>
|
||||
<entry>
|
||||
Description
|
||||
</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody valign="top">
|
||||
<row>
|
||||
<entry>
|
||||
<literal>Default Scopes</literal>
|
||||
</entry>
|
||||
<entry>
|
||||
Allows you to manually specify the scopes that users must authorize when authenticating with this provider. For a complete list of scopes, please take a look at <ulink url="https://msdn.microsoft.com/en-us/library/hh243646.aspx">https://msdn.microsoft.com/en-us/library/hh243646.aspx</ulink>. By default, Keycloak uses the following scopes: <literal>wl.basic,wl.emails</literal>
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</section>
|
||||
<section>
|
||||
<title>StackOverflow</title>
|
||||
<para>
|
||||
@@ -1282,7 +1371,7 @@ keycloak.createLoginUrl({
|
||||
<section>
|
||||
<title>Mapping/Importing User profile data from Social Identity Provider</title>
|
||||
<para>
|
||||
You can import user profile data provided by social identity providers like Google, GitHub, LinkedIn, Stackoverflow and Facebook
|
||||
You can import user profile data provided by social identity providers like Google, GitHub, LinkedIn, Microsoft, Stackoverflow and Facebook
|
||||
into new Keycloak user created from given social accounts. After you configure a broker, you'll see a <literal>Mappers</literal>
|
||||
button appear. Click on that and you'll get to the list of mappers that are assigned to this broker. There is a
|
||||
<literal>Create</literal> button on this page. Clicking on this create button allows you to create a broker mapper.
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
<title>Javascript Adapter</title>
|
||||
<para>
|
||||
The Keycloak Server comes with a Javascript library you can use to secure HTML/Javascript applications. This
|
||||
library is referencable directly from the keycloak server. You can also download the adapter from Keycloak's download
|
||||
site if you want a static copy of this library. It
|
||||
library is referenceable directly from the keycloak server. You can also download the adapter from Keycloak's download
|
||||
site if you want a static copy. It
|
||||
works in the same way as other application adapters except that your browser is driving the OAuth redirect protocol
|
||||
rather than the server.
|
||||
</para>
|
||||
@@ -14,13 +14,13 @@
|
||||
<para>
|
||||
To use this adapter, you must first configure an application (or client) through the <literal>Keycloak Admin Console</literal>.
|
||||
You should select <literal>public</literal> for the <literal>Client Type</literal> field. As public clients can't
|
||||
be verified with a client secret you are required to configure one or more valid redirect uris as well.
|
||||
Once you've configured the application click on the <literal>Installation</literal> tab and download the <literal>keycloak.json</literal>
|
||||
file. This file should be hosted in your web-server at the same root as your HTML pages. Alternatively you can either
|
||||
specify the URL for this file, or manually configure the adapter.
|
||||
be verified with a client secret, you are required to configure one or more valid redirect uris.
|
||||
Once you've configured the application, click on the <literal>Installation</literal> tab and download the <literal>keycloak.json</literal>
|
||||
file. This file should be hosted on your web-server at the same root as your HTML pages. Alternatively, you can manually
|
||||
configure the adapter and specify the URL for this file.
|
||||
</para>
|
||||
<para>
|
||||
Next you have to initialize the adapter in your application. An example on how to do this is shown below.
|
||||
Next, you have to initialize the adapter in your application. An example is shown below.
|
||||
<programlisting><![CDATA[
|
||||
<head>
|
||||
<script src="http://<keycloak server>/auth/js/keycloak.js"></script>
|
||||
@@ -47,7 +47,7 @@ var keycloak = Keycloak({
|
||||
});
|
||||
]]></programlisting>
|
||||
You can also pass <literal>login-required</literal> or <literal>check-sso</literal> to the init function. Login
|
||||
required will redirect to the login form on the server, while check-sso will redirect to the auth server to check
|
||||
required will cause a redirect to the login form on the server, while check-sso will simply redirect to the auth server to check
|
||||
if the user is already logged in to the realm. For example:
|
||||
<programlisting><![CDATA[
|
||||
keycloak.init({ onLoad: 'login-required' })
|
||||
@@ -111,9 +111,9 @@ keycloak.init({ onLoad: 'login-required' })
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To refresh the token if it's expired call the <literal>updateToken</literal> method. This method returns a promise
|
||||
object which can be used to invoke a function on success or failure. This method can be used to wrap functions
|
||||
that should only be called with a valid token. For example the following method will refresh the token if it
|
||||
To refresh the token when it is expired, call the <literal>updateToken</literal> method. This method returns a promise
|
||||
object, which can be used to invoke a function on success or failure. This method can be used to wrap functions
|
||||
that should only be called with a valid token. For example, the following method will refresh the token if it
|
||||
expires within 30 seconds, and then invoke the specified function. If the token is valid for more than 30 seconds it
|
||||
will just call the specified function.
|
||||
<programlisting><![CDATA[
|
||||
@@ -129,7 +129,7 @@ keycloak.updateToken(30).success(function() {
|
||||
<title>Session status iframe</title>
|
||||
|
||||
<para>
|
||||
By default the JavaScript adapter creates a non-visible iframe that is used to detect if a single-sign out has occured.
|
||||
By default, the JavaScript adapter creates a non-visible iframe that is used to detect if a single-sign out has occurred.
|
||||
This does not require any network traffic, instead the status is retrieved from a special status cookie. This feature can be disabled
|
||||
by setting <literal>checkLoginIframe: false</literal> in the options passed to the <literal>init</literal>
|
||||
method.
|
||||
@@ -140,33 +140,32 @@ keycloak.updateToken(30).success(function() {
|
||||
<title>Implicit and Hybrid Flow</title>
|
||||
|
||||
<para>
|
||||
By default the JavaScript adapter uses <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth">OpenID Connect standard (Authorization code) flow</ulink>, which
|
||||
means that after authentication will Keycloak server redirects back to your application and Javascript adapter will exchange <literal>code</literal> for access token and refresh token.
|
||||
By default, the JavaScript adapter uses <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth">OpenID Connect standard (Authorization code) flow</ulink>, which
|
||||
means that after authentication, the Keycloak server redirects the user back to your application, where the JavaScript adapter will exchange the <literal>code</literal> for an access token and a refresh token.
|
||||
</para>
|
||||
<para>
|
||||
However Keycloak also supports <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth">OpenID Connect Implicit flow</ulink>
|
||||
where access token is directly sent after successful authentication from Keycloak and there is no additional request for exchange code.
|
||||
This might have better performance than standard flow as there is no additional request for exchange code-to-token. However sending access token
|
||||
in URL fragment might be security issue in some environments (Token can be more easily stolen from the network etc).
|
||||
However, Keycloak also supports <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth">OpenID Connect Implicit flow</ulink>
|
||||
where an access token is sent immediately after successful authentication with Keycloak (there is no additional request for exchange code).
|
||||
This could have better performance than standard flow, as there is no additional request to exchange the code for tokens. However, sending the access token
|
||||
in the URL fragment could pose a security issue in some environments (access logs might expose tokens located in the URL).
|
||||
</para>
|
||||
<para>To enable implicit flow, you need to enable the flag <literal>Implicit Flow Enabled</literal> for the client in Keycloak admin console. You also need to pass
|
||||
the parameter <literal>flow</literal> with value <literal>implicit</literal> to <literal>init</literal> method, so that Javascript adapter will use implicit flow instead of standard flow.
|
||||
The example is here:
|
||||
<para>To enable implicit flow, you need to enable the <literal>Implicit Flow Enabled</literal> flag for the client in the Keycloak admin console. You also need to pass
|
||||
the parameter <literal>flow</literal> with value <literal>implicit</literal> to <literal>init</literal> method.
|
||||
An example is below:
|
||||
<programlisting><![CDATA[
|
||||
keycloak.init({ flow: 'implicit' })
|
||||
]]></programlisting>
|
||||
Note that with implicit flow, you don't have refresh token available after authentication. This makes it harder for your application to periodically update
|
||||
access token in background (without browser redirection). It's recommended that you implement <literal>onTokenExpired</literal> callback method on keycloak object, so you
|
||||
have possibility to do something after token is expired (For example you can call keycloak.login, which will redirect browser to Keycloak login screen and it will immediately
|
||||
redirect you back if SSO session is still valid and user is still logged. However make sure to save the application state before doing redirect.)
|
||||
Note that with implicit flow, you are not given a refresh token after authentication. This makes it harder for your application to periodically update
|
||||
the access token in background (without browser redirection). It's recommended that you implement an <literal>onTokenExpired</literal> callback method on the keycloak object, so you
|
||||
are notified after the token is expired (For example you can call keycloak.login, which will redirect browser to Keycloak login screen and it will immediately
|
||||
redirect you back if the SSO session is still valid and the user is still logged. However, make sure to save the application state before performing a redirect.)
|
||||
</para>
|
||||
<para>
|
||||
Keycloak also have support for <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth">OpenID Connect Hybrid flow</ulink>. This requires
|
||||
that client in admin console has both flags <literal>Standard Flow Enabled</literal> and <literal>Implicit Flow Enabled</literal> enabled in admin console.
|
||||
The Keycloak will send both the code and tokens to your application. Access token can be immediately used and in the meantime, code can be exchanged for access token and refresh token.
|
||||
Hybrid flow is good for performance similarly like implicit flow, because access token is available immediatelly to your application. But similarly like implicit flow, the token is
|
||||
sent in URL fragment, so security may not be so good.
|
||||
One advantage over implicit flow is, that you have also refresh token available in your application (after code-to-token request is finished in background).
|
||||
Keycloak also has support for <ulink url="http://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth">OpenID Connect Hybrid flow</ulink>. This requires
|
||||
the client to have both the <literal>Standard Flow Enabled</literal> and <literal>Implicit Flow Enabled</literal> flags enabled in the admin console.
|
||||
The Keycloak server will then send both the code and tokens to your application. The access token can be used immediately while the code can be exchanged for access and refresh tokens.
|
||||
Similar to the implicit flow, the hybrid flow is good for performance because the access token is available immediately. But, the token is still sent in the URL, and security risks might still apply.
|
||||
However, one advantage over the implicit flow is that a refresh token is made available to the application (after the code-to-token request is finished).
|
||||
</para>
|
||||
<para>
|
||||
For hybrid flow, you need to pass the parameter <literal>flow</literal> with value <literal>hybrid</literal> to <literal>init</literal> method.
|
||||
@@ -410,4 +409,4 @@ keycloak.onAuthSuccess = function() { alert('authenticated'); }
|
||||
</itemizedlist>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
Reference in new issue
Block a user