The OpenShift Enterprise master includes a built-in OAuth server. Users obtain OAuth
access tokens to authenticate themselves to the API.
When a person requests a new OAuth token, the OAuth server uses the configured
identity
provider
to determine the identity of the person making the request.
It then determines what user that identity maps to, creates an access token for
that user, and returns the token for use.
Every request for an OAuth token must specify the OAuth client that will
receive and use the token. The following OAuth clients are automatically created
when starting the OpenShift Enterprise API:
| OAuth Client |
Usage |
openshift-web-console |
Requests tokens for the web console. |
openshift-browser-client |
Requests tokens at <master>/oauth/token/request with a user-agent that can handle interactive logins. |
openshift-challenging-client |
Requests tokens with a user-agent that can handle WWW-Authenticate challenges. |
To register additional clients:
$ oc create -f <(echo '
{
"kind": "OAuthClient",
"apiVersion": "v1",
"metadata": {
"name": "demo" (1)
},
"secret": "...", (2)
"redirectURIs": [
"http://www.example.com/" (3)
]
}')
| 1 |
The name of the OAuth client is used as the client_id parameter when making requests to <master>/oauth/authorize and <master>/oauth/token. |
| 2 |
The secret is used as the client_secret parameter when making requests to <master>/oauth/token. |
| 3 |
The redirect_uri parameter specified in requests to <master>/oauth/authorize and <master>/oauth/token must be equal to (or prefixed by) one of the URIs in redirectURIs. |
All requests for OAuth tokens involve a request to <master>/oauth/authorize.
Most authentication integrations place an authenticating proxy in front of this
endpoint, or configure OpenShift Enterprise to validate credentials against a backing
identity
provider.
Requests to <master>/oauth/authorize can come from user-agents that cannot
display interactive login pages, such as the CLI. Therefore, OpenShift Enterprise
supports authenticating using a WWW-Authenticate challenge in addition to
interactive login flows.
If an authenticating proxy is placed in front of the
<master>/oauth/authorize endpoint, it should send unauthenticated,
non-browser user-agents WWW-Authenticate challenges, rather than displaying an
interactive login page or redirecting to an interactive login flow.
|
|
To prevent cross-site request forgery (CSRF) attacks against browser clients, Basic authentication challenges
should only be sent if a X-CSRF-Token header is present on the request. Clients that expect
to receive Basic WWW-Authenticate challenges should set this header to a non-empty value.
If the authenticating proxy cannot support WWW-Authenticate challenges, or if
OpenShift Enterprise is configured to use an identity provider that does not support
WWW-Authenticate challenges, users can visit <master>/oauth/token/request
using a browser to obtain an access token manually.
|
When requesting an OAuth token using the implicit grant flow (response_type=token) with a client_id configured to request WWW-Authenticate challenges (like openshift-challenging-client), these are the possible server responses from /oauth/authorize, and how they should be handled:
| Status |
Content |
Client response |
|
Location header containing an access_token parameter in the URL fragment (RFC 4.2.2)
|
Use the access_token value as the OAuth token
|
|
Location header containing an error query parameter (RFC 4.1.2.1)
|
Fail, optionally surfacing the error (and optional error_description) query values to the user
|
|
|
Follow the redirect, and process the result using these rules
|
|
WWW-Authenticate header present
|
Respond to challenge if type is recognized (e.g. Basic, Negotiate, etc), resubmit request, and process the result using these rules
|
|
WWW-Authenticate header missing
|
No challenge authentication is possible. Fail and show response body (which might contain links or details on alternate methods to obtain an OAuth token)
|
|
|
Fail, optionally surfacing response body to the user
|
