KEYCLOAK-9319 fixes in developer guide

This commit is contained in:
Matthew Helmke 2019-01-15 07:24:22 -06:00 committed by Stian Thorgersen
parent 8a40cce8fb
commit cb1b73930f
14 changed files with 27 additions and 27 deletions

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -1,19 +1,19 @@
=== Client Initiated Account Linking
=== Client-initiated Account Linking
Some applications want to integrate with social providers like Facebook, but do not want to provide an option to login via
these social providers. {project_name} offers a browser-based API that applications can use to link an existing
user account to a specific external IDP. This is called client initiated account linking.
user account to a specific external IDP. This is called client-initiated account linking. Account linking can only be initiated by OIDC applications.
The way it works is that the application forward's the user's browser to a URL on the {project_name} server requesting
The way it works is that the application forwards the user's browser to a URL on the {project_name} server requesting
that it wants to link the user's account to a specific external provider (i.e. Facebook). The server
initiates a login with the external provider. The browser logs in at the external provider and is redirected
back to the auth server. The auth server establishes the link and redirects back to the application with a confirmation.
back to the server. The server establishes the link and redirects back to the application with a confirmation.
There are some preconditions that must be met by the client application before it can initiate this protocol:
* The desired identity provider must be configured and enabled for the user's realm in the admin console.
* The application must already be logged in as an existing user via the OIDC protocol
* The user account must already be logged in as an existing user via the OIDC protocol
* The user must have an `account.manage-account` or `account.manage-account-links` role mapping.
* The application must be granted the scope for those roles within its access token
* The application must have access to its access token as it needs information within it to generate the redirect URL.

View file

@ -5,11 +5,11 @@
{project_name} is designed to cover most use-cases without requiring custom code, but we also want it to be customizable.
To achieve this {project_name} has a number of Service Provider Interfaces (SPI) for which you can implement your own providers.
=== Implementing a SPI
=== Implementing an SPI
To implement an SPI you need to implement its ProviderFactory and Provider interfaces. You also need to create a service configuration file.
For example, to implement the Theme Selector Spi you need to implement ThemeSelectorProviderFactory and ThemeSelectorProvider and also provide the file
For example, to implement the Theme Selector SPI you need to implement ThemeSelectorProviderFactory and ThemeSelectorProvider and also provide the file
`META-INF/services/org.keycloak.theme.ThemeSelectorProviderFactory`.
Example ThemeSelectorProviderFactory:
@ -47,7 +47,7 @@ public class MyThemeSelectorProviderFactory implements ThemeSelectorProviderFact
----
NOTE: Keycloak creates a single instance of provider factories which makes it possible to store state for multiple requests.
Provider instances are created by calling create on the factory for each requests so these should be light-weight object.
Provider instances are created by calling create on the factory for each request so these should be light-weight object.
Example ThemeSelectorProvider:
@ -83,7 +83,7 @@ org.acme.provider.MyThemeSelectorProviderFactory
You can configure your provider through `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
See the link:{installguide_link}[{installguide_name}] for more details on
where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.
where to find these files.
For example by adding the following to `standalone.xml`:
@ -129,7 +129,7 @@ public class MyThemeSelectorProvider implements EventListenerProvider {
[[_providers_admin_console]]
==== Show info from your SPI implementation in admin console
Sometimes it is useful to show additional info about your Provider to a {project_name} administrator. You can show provider build time informations (eg. version of
Sometimes it is useful to show additional info about your Provider to a {project_name} administrator. You can show provider build time information (eg. version of
custom provider currently installed), current configuration of the provider (eg. url of remote system your provider talks to) or some operational info
(average time of response from remote system your provider talks to). {project_name} admin console provides Server Info page to show this kind of information.

View file

@ -25,7 +25,7 @@ NOTE: To set the theme for the `master` admin console you need to set the admin
refresh the page.
To change the welcome theme you need to edit `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
For more information on where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file resides see the link:{installguide_link}[{installguide_name}].
For more information on where these files reside see the link:{installguide_link}[{installguide_name}].
Add `welcomeTheme` to the theme element, for example:
@ -43,7 +43,7 @@ If the server is running you need to restart the server for the changes to the w
=== Default Themes
{project_name} comes bundled with default themes in the server's root `themes` directory. To simplify upgrading you should not edit the bundled themes
directly. Instead create your own theme that extends one of the bundle themes.
directly. Instead create your own theme that extends one of the bundled themes.
=== Creating a Theme
@ -117,7 +117,7 @@ You can also add your own custom properties and use them from custom templates.
==== Stylesheets
A theme can have one or more stylesheets, to add a stylesheet create a file in the `<THEME TYPE>/resources/css` directory of your theme. Then add it to the `styles`
A theme can have one or more stylesheets. To add a stylesheet create a file in the `<THEME TYPE>/resources/css` directory of your theme. Then add it to the `styles`
property in `theme.properties`.
For example to add `styles.css` to the `mytheme` create `themes/mytheme/login/resources/css/styles.css` with the following content:
@ -192,7 +192,7 @@ Or to use directly in HTML templates add the following to a custom HTML template
==== Messages
Text in the templates are loaded from message bundles. A theme that extends another theme will inherit all messages from the parents message bundle and you can
Text in the templates is loaded from message bundles. A theme that extends another theme will inherit all messages from the parent's message bundle and you can
override individual messages by adding `<THEME TYPE>/messages/messages_en.properties` to your theme.
For example to replace `Username` on the login form with `Your Username` for the `mytheme` create the file
@ -278,7 +278,7 @@ Check out the https://freemarker.apache.org/docs/index.html[FreeMarker Manual] f
==== Emails
To edit the subject and contents for emails, for example password recovery email, add a message bundle to the `email` type of your theme. There's three messages for each email. One for the subject, one for the plain text body and one for the html body.
To edit the subject and contents for emails, for example password recovery email, add a message bundle to the `email` type of your theme. There are three messages for each email. One for the subject, one for the plain text body and one for the html body.
To see all emails available take a look at `themes/base/email/messages/messages_en.properties`.
@ -293,7 +293,7 @@ passwordResetBodyHtml=<a href="{0}">Reset password</a>
=== Deploying Themes
Themes can be deployed to {project_name} by copying the theme directory to `themes` or it can be deployed as an archive. During development copying the
Themes can be deployed to {project_name} by copying the theme directory to `themes` or it can be deployed as an archive. During development you can copy the
theme to the `themes` directory, but in production you may want to consider using an `archive`. An `archive` makes it simpler to have a versioned copy of
the theme, especially when you have multiple instances of {project_name} for example with clustering.

View file

@ -8,7 +8,7 @@ Also note that provider JARs can make use of the `jboss-deployment-structure.xml
can use in a {appserver_name} environment. For more details on this file, see the {appserver_name} documentation. It
allows you to pull in external dependencies among other fine-grained actions.
Implementations of `UserStorageProviderFactory` are required to be plain java objects. But we also currently support
Provider implementations are required to be plain java objects. But we also currently support
implementing `UserStorageProvider` classes as Stateful EJBs. This is especially useful if you want to use JPA
to connect to a relational store. This is how you would do it:

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services</orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>

View file

@ -10,7 +10,7 @@
<orgname>Red Hat Customer Content Services </orgname>
</authorgroup>
<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
<para> Copyright <trademark class="copyright"></trademark> 2018 Red Hat, Inc. </para>
<para> Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. </para>
<para>Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</para>