Minor changes for Clients chapter.
This commit is contained in:
Stan Silvert
parent
be0c701875
commit
c02c169146
7 changed files with 32 additions and 32 deletions
|
|
@ -2,9 +2,9 @@
|
|||
== Managing Clients
|
||||
|
||||
Clients are entities that can request authentication of a user. Clients come in two forms.
|
||||
he first type of client is an application that wants
|
||||
The first type of client is an application that wants
|
||||
to participate in single-sign-on. These clients just want {{book.project.name}} to provide security for them. The other type
|
||||
of client is one that is requesting an access token so that it can invoke on other services on behalf of the authenticated user.
|
||||
of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.
|
||||
This section discusses various aspects around configuring clients and various ways to do it.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
=== OIDC Clients
|
||||
|
||||
<<fake/../../sso-protocols/oidc.adoc#_oidc,OpenID Connect>> is the preferred protocol to secure applications. It was designed from the ground up to be web friendly
|
||||
and works best with HTML5/JavaScript applications.
|
||||
and work best with HTML5/JavaScript applications.
|
||||
|
||||
To create a OIDC client go to the `Clients` left menu item. On this page you'll see a `create` button on the right.
|
||||
To create an OIDC client go to the `Clients` left menu item. On this page you'll see a `Create` button on the right.
|
||||
|
||||
.Clients
|
||||
image:../../{{book.images}}/clients.png[]
|
||||
|
|
@ -15,7 +15,7 @@ This will bring you to the `Add Client` page.
|
|||
.Add Client
|
||||
image:../../{{book.images}}/add-client-oidc.png[]
|
||||
|
||||
Enter in the `Client ID` of the client. This should be a simple string
|
||||
Enter in the `Client ID` of the client. This should be a simple
|
||||
alpha-numeric string that will be used in requests and in the {{book.project.name}} database to identity the client.
|
||||
Next select `openid-connect` in the `Client Protocol` drop down box.
|
||||
Ignore the `Client Template` listbox for now,
|
||||
|
|
@ -58,14 +58,14 @@ If you've ever done a social login to Google, you'll often see a similar page.
|
|||
This defines the type of the OIDC client.
|
||||
|
||||
_confidential_::
|
||||
Confidential access type is for clients that need to perform a browser login and that you want to require a client secret when they turn an access code into an access token,
|
||||
(see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). The advantages of this is that it is a little extra security.
|
||||
Confidential access type is for clients that need to perform a browser login and require a client secret when they turn an access code into an access token,
|
||||
(see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details). The advantage of this is that it is a little extra security.
|
||||
Since {{book.project.name}} requires you to register valid redirect-uris, we're not exactly sure what this little extra security is though.
|
||||
:) The disadvantages of this access type is that confidential access type is pointless for pure JavaScript clients as anybody could easily figure out your client's secret!
|
||||
|
||||
_public_::
|
||||
Public access type is for clients that need to perform a browser login and that you feel that the added extra security of confidential access type is not needed.
|
||||
FYI, Pure javascript clients are by nature public.
|
||||
Pure javascript clients are by nature public.
|
||||
|
||||
_bearer-only_::
|
||||
Bearer-only access type means that the application only allows bearer token requests.
|
||||
|
|
@ -84,7 +84,7 @@ This is a required field. Enter in a URL pattern and click the + sign to add.
|
|||
Remember that you still have to click the `Save` button!
|
||||
Only wildcards, * ,are allowed at the end of of a URI, i.e. http://host.com/*
|
||||
|
||||
You should take extra precautions when registering valid redirect URI patterns as if you make
|
||||
You should take extra precautions when registering valid redirect URI patterns. If you make
|
||||
them too general you are vulnerable to attacks. See <<fake/../../threat/redirect.adoc#_unspecific-redirect-uris, Threat Model Mitigation>> chapter
|
||||
for more information.
|
||||
|
||||
|
|
@ -114,8 +114,8 @@ See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more informa
|
|||
*Web Origins*
|
||||
|
||||
This option centers around link:http://www.w3.org/TR/cors/[CORS] which stands for Cross-Origin Resource Sharing.
|
||||
If executing browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different than the one the
|
||||
JavaScript code came from, then the request uses the CORS.
|
||||
If browser JavaScript tries to make an AJAX HTTP request to a server whose domain is different from the one the
|
||||
JavaScript code came from, then the request must use CORS.
|
||||
The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed.
|
||||
This protocol exists to protect against XSS, CSRF and other JavaScript-based attacks.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
Both POST and Redirect bindings are supported.
|
||||
You can choose to require client signature validation and can have the server sign and/or encrypt responses as well.
|
||||
|
||||
To create a SAML client go to the `Clients` left menu item. On this page you'll see a `create` button on the right.
|
||||
To create a SAML client go to the `Clients` left menu item. On this page you'll see a `Create` button on the right.
|
||||
|
||||
.Clients
|
||||
image:../../{{book.images}}/clients.png[]
|
||||
|
|
@ -23,7 +23,7 @@ we'll go over that later in this chapter.
|
|||
Finally enter in the `Client SAML Endpoint` URL. Enter the
|
||||
URL you want the {{book.project.name}} server to send SAML requests and responses to. Usually applications have only one URL for processing SAML requests.
|
||||
If your application has different URLs for its bindings, don't worry, you can fix this in the `Settings` tab of the client.
|
||||
application in the `Root URL` field and click `Save`. This will create the client and bring you to the client `Settings`
|
||||
Click `Save`. This will create the client and bring you to the client `Settings`
|
||||
tab.
|
||||
|
||||
.Client Settings
|
||||
|
|
@ -82,7 +82,7 @@ Force POST Binding::
|
|||
|
||||
Front Channel Logout::
|
||||
If true, this application requires a browser redirect to be able to perform a logout.
|
||||
For example, the application may require a cookie to be reset which could only be done by a done via a redirect.
|
||||
For example, the application may require a cookie to be reset which could only be done via a redirect.
|
||||
If this switch is false, then {{book.project.name}} will invoke a background SAML request to logout the application.
|
||||
|
||||
Force Name ID Format::
|
||||
|
|
@ -106,7 +106,7 @@ Base URL::
|
|||
If {{book.project.name}} needs to link to the client, this URL would be used.
|
||||
|
||||
Master SAML Processing URL::
|
||||
This URL will be used for all SAML requests and responsed directed to the SP.
|
||||
This URL will be used for all SAML requests and the response will be directed to the SP.
|
||||
It will be used as the Assertion Consumer Service URL and the Single Logout Service URL.
|
||||
If a login request contains the Assertion Consumer Service URL, that will take precedence, but this URL must be valided by a registered Valid Redirect URI pattern
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
|
||||
=== Generating Client Adapter Config
|
||||
|
||||
The {{book.project.name}} can pre-generate configure files that you can use to install a client adapter for in your application's
|
||||
The {{book.project.name}} can pre-generate configuration files that you can use to install a client adapter for in your application's
|
||||
deployment environment. A number of adapter types are supported for both OIDC and SAML. Go to the `Installation` tab of the
|
||||
client you want to generate configuration for.
|
||||
|
||||
image:../../{{book.images}}/client-installation.png[]
|
||||
|
||||
Select the `format option` you want configuration generated for. All {{book.project.name}} client adapters for OIDC and SAML
|
||||
Select the `Format Option` you want configuration generated for. All {{book.project.name}} client adapters for OIDC and SAML
|
||||
are supported. The mod-auth-mellon Apache HTTPD adapter for SAML is supported as well as standard SAML entity descriptor files.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ type of client you have to configure the client's credentials.
|
|||
.Credentials Tab
|
||||
image:../../../{{book.images}}/client-credentials.png[]
|
||||
|
||||
The `Client Authenticator` list box is the type of credential you are going to use for your confidential client.
|
||||
The `Client Authenticator` list box specifies the type of credential you are going to use for your confidential client.
|
||||
It defaults to client ID and secret. The secret is automatically generated for you and the `Regenerate Secret`
|
||||
button allows you to recreate this secret if you want or need to.
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ generate these via an external tool and just import the client's certificate.
|
|||
.Import Certificate
|
||||
image:../../../{{book.images}}/import-client-cert.png[]
|
||||
|
||||
There's multiple formats you can import from, just choose the archive format you have the certificate stored in,
|
||||
There are multiple formats you can import from, just choose the archive format you have the certificate stored in,
|
||||
select the file, and click the `Import` button.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
=== Service Accounts
|
||||
|
||||
Each OIDC client has a built in _service account_ which allows them to obtain an access token.
|
||||
Each OIDC client has a built in _service account_ which allows it to obtain an access token.
|
||||
This is covered in the OAuth 2.0 specifiation under <<fake/../../../sso-protocols/oidc.adoc#_oidc-auth-flows,Client Credentials Grant>>
|
||||
To use this feature you must set the <<fake/../../../clients/client-oidc.adoc#_access-type, Access Type>> of your client to `confidential`. When you do this,
|
||||
the `Service Accounts Enabled` switch will appear. You need to turn on this switch. Also make sure that you have
|
||||
|
|
@ -10,14 +10,14 @@ configured your <<fake/../../../clients/oidc/confidential.adoc#_client-credentia
|
|||
|
||||
To use it you must have registered a valid `confidential` Client and you need to check the switch `Service Accounts Enabled` in {{book.project.name}} admin console for this client.
|
||||
In tab `Service Account Roles` you can configure the roles available to the service account retrieved on behalf of this client.
|
||||
Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are intersection of scopes and the service account roles.
|
||||
Don't forget that you need those roles to be available in Scopes of this client as well (unless you have `Full Scope Allowed` on). As in normal login, roles from access token are the intersection of scopes and the service account roles.
|
||||
|
||||
The REST URL to invoke on is `/\{server-root-usualy-auth}/realms/\{realm-name}/protocol/openid-connect/token`.
|
||||
Invoking on this URL is a POST request and requires you to post the client credentials.
|
||||
By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate client with signed JWT assertion or any other custom mechanism for client authentication.
|
||||
You also need to use parameter `grant_type=client_credentials` as per OAuth2 specification.
|
||||
By default, client credentials are represented by clientId and clientSecret of the client in `Authorization: Basic` header, but you can also authenticate the client with a signed JWT assertion or any other custom mechanism for client authentication.
|
||||
You also need to use the parameter `grant_type=client_credentials` as per the OAuth2 specification.
|
||||
|
||||
For example the POST invocation to retrieve service account can look like this:
|
||||
For example the POST invocation to retrieve a service account can look like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
@ -50,4 +50,4 @@ Pragma: no-cache
|
|||
}
|
||||
----
|
||||
|
||||
The retrieved access token can be refreshed or logged out by out-of-bound request.
|
||||
The retrieved access token can be refreshed or logged out by an out-of-bound request.
|
||||
|
|
|
|||
|
|
@ -15,19 +15,19 @@ an OIDC based client.
|
|||
.Mappers Tab
|
||||
image:../../{{book.images}}/mappers-oidc.png[]
|
||||
|
||||
Every client has a bunch of built-in mappers that are created for it by default. They map things like, for example, email address to
|
||||
a specific claim in the identity and access token. Their function should each be self explanatory from their name. There's
|
||||
is additional pre-configured mappers that are not attached to the client that you can add
|
||||
Each client has several built-in mappers that are created for it by default. They map things like, for example, email address to
|
||||
a specific claim in the identity and access token. Their function should each be self explanatory from their name. There
|
||||
are additional pre-configured mappers that are not attached to the client that you can add
|
||||
by clicking the `Add Builtin` button.
|
||||
|
||||
Each mapper has common settings as well as additional ones depending on which type of mapper you are adding. Click the `edit` button
|
||||
Each mapper has common settings as well as additional ones depending on which type of mapper you are adding. Click the `Edit` button
|
||||
next to one of the mappers in the list to get to the config screen.
|
||||
|
||||
.Mapper Config
|
||||
image:../../{{book.images}}/mapper-config.png[]
|
||||
|
||||
The best way to find out what a config option is is to moveover the tooltips. There are a few config options that
|
||||
are common to all mappers.
|
||||
The best way to learn about a config option is to hover over its tooltip. There are a few config options that
|
||||
are common to all mappers:
|
||||
|
||||
Consent::
|
||||
If your client requires consent, this mapper will be displayed on the consent screen shown to the user.
|
||||
|
|
@ -40,7 +40,7 @@ Consent Text::
|
|||
Most OIDC mappers also allow you to control where the claim gets put. You can opt to include or exclude the claim from both the
|
||||
_id_ and _access_ tokens by fiddling with the `Add to ID token` and `Add to access token` switches.
|
||||
|
||||
Finaly, you can also add other mapper types. if you go back to the `Mappers` tab, click the `Create` button.
|
||||
Finally, you can also add other mapper types. If you go back to the `Mappers` tab, click the `Create` button.
|
||||
|
||||
.Add Mapper
|
||||
image:../../{{book.images}}/add-mapper.png[]
|
||||
|
|
|
|||
Loading…
Reference in a new issue