139 lines
6.3 KiB
Text
139 lines
6.3 KiB
Text
|
|
=== 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 work best with HTML5/JavaScript applications.
|
|
|
|
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[]
|
|
|
|
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
|
|
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,
|
|
we'll go over that later in this chapter.
|
|
Finally enter in the base URL of your
|
|
application in the `Root URL` field and click `Save`. This will create the client and bring you to the client `Settings`
|
|
tab.
|
|
|
|
.Client Settings
|
|
image:../../{{book.images}}/client-settings-oidc.png[]
|
|
|
|
Let's walk through each configuration item on this page.
|
|
|
|
*Client ID*
|
|
|
|
This specifies an alpha-numeric string that will be used as the client identifier for OIDC requests.
|
|
|
|
*Name*
|
|
|
|
This is the display name for the client whenever it is displayed in a {{book.project.name}} UI screen. You can localize
|
|
the value of this field by setting up a replacement string value i.e. $\{myapp}. See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
|
|
for more information.
|
|
|
|
*Description*
|
|
This specifies the description of the client. This can also be localized.
|
|
|
|
*Enabled*
|
|
|
|
If this is turned off, the client will not be allowed to request authentication.
|
|
|
|
*Consent Required*
|
|
|
|
If this is on, then users will get a consent page which asks the user if they grant access to that application. It will also
|
|
display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to.
|
|
If you've ever done a social login to Google, you'll often see a similar page. {{book.project.name}} provides the same functionality.
|
|
|
|
[[_access-type]]
|
|
*Access Type*
|
|
|
|
This defines the type of the OIDC client.
|
|
|
|
_confidential_::
|
|
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.
|
|
Pure javascript clients are by nature public.
|
|
|
|
_bearer-only_::
|
|
Bearer-only access type means that the application only allows bearer token requests.
|
|
If this is turned on, this application cannot participate in browser logins.
|
|
|
|
_direct access only_::
|
|
This switch is for clients that only use the <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Direct Access Grant>> protocol to obtain access tokens.
|
|
|
|
*Root URL*
|
|
|
|
If {{book.project.name}} uses any configured relative URLs, this value is prepended to them.
|
|
|
|
*Valid Redirect URIs*
|
|
|
|
This is a required field. Enter in a URL pattern and click the + sign to add. Click the - sign next to URLs you want to remove.
|
|
Remember that you still have to click the `Save` button!
|
|
Wildcards (\*) are only allowed at the end of of a URI, i.e. http://host.com/*
|
|
|
|
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.
|
|
|
|
*Base URL*
|
|
|
|
If {{book.project.name}} needs to link to the client, this URL would be used.
|
|
|
|
*Standard Flow Enabled*
|
|
|
|
If this is on, clients are allowed to use the OIDC <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Authorization Code Flow>>.
|
|
|
|
*Implicit Flow Enabled*
|
|
|
|
If this is on, clients are allowed to use the OIDC <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Implicit Flow>>.
|
|
|
|
*Direct Grants Enabled*
|
|
|
|
If this is on, clients are allowed to use the OIDC <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Direct Grants>>.
|
|
|
|
*Admin URL*
|
|
|
|
For {{book.project.name}} specific client adapters, this is the callback endpoint for the client. The {{book.project.name}}
|
|
server will use this URI to make callbacks like pushing revocation policies, performing backchannel logout, and other
|
|
administrative operations. For {{book.project.name}} servlet adapters, this can be the root URL of the servlet application.
|
|
See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
|
|
|
|
*Web Origins*
|
|
|
|
This option centers around link:http://www.w3.org/TR/cors/[CORS] which stands for Cross-Origin Resource Sharing.
|
|
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.
|
|
|
|
{{book.project.name}} has support for validated CORS requests. The way it works is that the domains listed in the
|
|
`Web Origins` setting for the client are embedded within the access token sent to the client application. The client
|
|
application can then use this information to decide whether or not to allow a CORS request to be invoked on it. This is
|
|
an extension to the OIDC protocol so only {{book.project.name}} client adapters support this feature.
|
|
See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
|
|
|
|
To fill in the `Web Origins` data, enter in a base URL and click the + sign to add. Click the - sign next to URLs you want to remove.
|
|
Remember that you still have to click the `Save` button!
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|