diff --git a/_build_cfg.yml b/_build_cfg.yml index b0b6c2a59f71..0ecdbf3e948f 100644 --- a/_build_cfg.yml +++ b/_build_cfg.yml @@ -125,6 +125,10 @@ Topics: File: overview - Name: Installing OpenShift File: admin_install_openshift + - Name: Master and Node Configuration + File: master_node_configuration + - Name: Configuring Authentication + File: configuring_authentication - Name: Managing Nodes File: manage_nodes - Name: Scheduler @@ -185,8 +189,6 @@ Topics: File: generate_cmd - Name: Output Build Dependencies File: output_deps - - Name: Launching Configuration - File: master_node_configuration - Name: JBoss Tools IDE File: jboss_tools diff --git a/admin_guide/configuring_authentication.adoc b/admin_guide/configuring_authentication.adoc new file mode 100644 index 000000000000..d303022f463a --- /dev/null +++ b/admin_guide/configuring_authentication.adoc @@ -0,0 +1,533 @@ += Configuring Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: + +toc::[] + +== Overview +The OpenShift +link:../architecture/infrastructure_components/kubernetes_infrastructure.html#master[master] +includes a built-in +link:../architecture/additional_concepts/authentication.html#oauth[OAuth +server]. Developers and administrators obtain +link:../architecture/additional_concepts/authentication.html#api-authentication[OAuth +access tokens] to authenticate themselves to the API. + +As an administrator, you can configure OAuth using a +link:master_node_configuration.html[master configuration file] to specify an +link:#identity-provider[identity provider]. When running a master without a +configuration file, the +link:#AllowAllPasswordIdentityProvider[`*AllowAllPasswordIdentityProvider*`] +identity provider is used by default, which allows any non-empty user name and +password to log in. This is useful for testing purposes. + +To use other link:#identity-providers[identity providers], or to modify any +link:#token-options[token], link:#grant-options[grant], or +link:#session-options[session options], you must run the master from a +configuration file. + +== Identity Providers +You can configure the master for authentication using your desired identity +provider by modifying the link:master_node_configuration.html[master +configuration file]. The following sections detail the identity providers +supported by OpenShift. + +=== Allow All [[AllowAllPasswordIdentityProvider]] +Set `*AllowAllPasswordIdentityProvider*` in the `*identityProviders*` stanza to +allow any non-empty user name and password to log in. This is the default +identity provider when running OpenShift without a +link:master_node_configuration.html[master configuration file]. + +.Master Configuration Using `*AllowAllPasswordIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: my_allow_provider <1> + challenge: true <2> + login: true <3> + provider: + apiVersion: v1 + kind: AllowAllPasswordIdentityProvider +---- +<1> This provider name is prefixed to user names to form an identity name. +<2> When `true`, unauthenticated token requests from non-web clients (like +the CLI) are sent a `WWW-Authenticate` challenge header for this provider. +<3> When `true`, unauthenticated token requests from web clients (like the +Management Console) are redirected to a login page backed by this provider. +==== + +=== Deny All [[DenyAllPasswordIdentityProvider]] +Set `*DenyAllPasswordIdentityProvider*` in the `*identityProviders*` stanza to deny +access for all user name and passwords. + +.Master Configuration Using `*DenyAllPasswordIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: my_deny_provider <1> + challenge: true <2> + login: true <3> + provider: + apiVersion: v1 + kind: DenyAllPasswordIdentityProvider +---- +<1> This provider name is prefixed to user names to form an identity name. +<2> When `true`, unauthenticated token requests from non-web clients (like the +CLI) are sent a `WWW-Authenticate` challenge header for this provider. +<3> When `true`, unauthenticated token requests from web clients (like the +Management Console) are redirected to a login page backed by this provider. +==== + +=== HTPasswd [[HTPasswdPasswordIdentityProvider]] + +Set `*HTPasswdPasswordIdentityProvider*` in the `*identityProviders*` stanza to +validate user names and passwords against a flat file generated using +http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. + +Only MD5 and SHA encryption types are supported. MD5 encryption is recommended, +and is the default for `htpasswd`. Plaintext, crypt, and bcrypt hashes are not +currently supported. + +The flat file is re-read if its modification time changes, without requiring a +server restart. + +To create the file, run: + +**** +`$ htpasswd -c __ __` +**** + +To add or update a login to the file, run: + +**** +`$ htpasswd __ __` +**** + +To remove a login from the file, run: + +**** +`$ htpasswd __ -D __` +**** + +.Master Configuration Using `*HTPasswdPasswordIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: my_htpasswd_provider <1> + challenge: true <2> + login: true <3> + provider: + apiVersion: v1 + kind: HTPasswdPasswordIdentityProvider + file: /path/to/users.htpasswd <4> +---- +<1> This provider name is prefixed to user names to form an identity name. +<2> When `true`, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider. +<3> When `true`, unauthenticated token requests from web clients (like the Management Console) are redirected to a login page backed by this provider. +<4> File generated using http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. +==== + +=== Basic Authentication (Remote) [[BasicAuthPasswordIdentityProvider]] + +Set `*BasicAuthPasswordIdentityProvider*` in the `*identityProviders*` stanza to +validate user names and passwords against a remote server using a +server-to-server Basic authentication request. User names and passwords are +validated against a remote URL that is protected by Basic authentication and +returns JSON. + +A `401` response indicates failed authentication. + +A non-`200` status, or the presence of a non-empty "error" key, indicates an error: + +---- +{"error":"Error message"} +---- + +A `200` status with a `sub` (subject) key indicates success: + +---- +{"sub":"userid"} <1> +---- +<1> The subject must be unique to the authenticated user and must not be able to be modified. + +A successful response may optionally provide additional data, such as: + +* A display name using the `name` key. For example: ++ +---- +{"sub":"userid", "name": "User Name", ...} +---- ++ +* An email address using the `email` key. For example: ++ +---- +{"sub":"userid", "email":"user@example.com", ...} +---- ++ +* A preferred user name using the `preferred_username` key. This is useful when the unique, unchangeable subject is a database key or UID, and a more human-readable name exists. This is used as a hint when provisioning the OpenShift user for the authenticated identity. For example: ++ +---- +{"sub":"014fbff9a07c", "preferred_username":"bob", ...} +---- + +.Master Configuration Using `*BasicAuthPasswordIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: my_remote_basic_auth_provider <1> + challenge: true <2> + login: true <3> + provider: + apiVersion: v1 + kind: BasicAuthPasswordIdentityProvider + url: https://www.example.com/remote-idp <4> + ca: /path/to/ca.file <5> + certFile: /path/to/client.crt <6> + keyFile: /path/to/client.key <7> +---- +<1> This provider name is prefixed to the returned user ID to form an identity name. +<2> When `true`, unauthenticated token requests from non-web clients (like the CLI) are sent a `WWW-Authenticate` challenge header for this provider. +<3> When `true`, unauthenticated token requests from web clients (like the Management Console) are redirected to a login page backed by this provider. +<4> URL accepting credentials in Basic authentication headers. +<5> Optional: Certificate bundle to use to validate server certificates for the configured URL. +<6> Optional: Client certificate to present when making requests to the configured URL. +<7> Key for the client certificate. Required if `*certFile*` is specified. +==== + +=== Request Header [[RequestHeaderIdentityProvider]] + +Set `*RequestHeaderIdentityProvider*` in the `*identityProviders*` stanza to +identify users from request header values, such as `X-Remote-User`. It is +typically used in combination with an authenticating proxy, which sets the +request header value. + +.Master Configuration Using `*RequestHeaderIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: my_request_header_provider <1> + challenge: false <2> + login: false <3> + provider: + apiVersion: v1 + kind: RequestHeaderIdentityProvider + clientCA: /path/to/client-ca.file <4> + headers: <5> + - X-Remote-User + - SSO-User +---- +<1> This provider name is prefixed to the user name in the request header to form an identity name. +<2> `*RequestHeaderIdentityProvider*` cannot be used to send `WWW-Authenticate` challenges. +<3> `*RequestHeaderIdentityProvider*` cannot be used to back a login page. +<4> Optional: PEM-encoded certificate bundle. If set, a valid client certificate must be presented and validated against the certificate authorities in the specified file before the request headers are checked for user names. +<5> Header names to check, in order, for user names. The first header containing a value is used as the user name. Required, case-insensitive. +==== + +=== GitHub [[GitHub]] + +Set `*GitHubIdentityProvider*` in the `*identityProviders*` stanza to use +https://github.com/[GitHub] as an identity provider, using the +https://developer.github.com/v3/oauth/[OAuth integration]. + +NOTE: Using GitHub as an identity provider requires users to get a token using `__/oauth/token/request` to use with command-line tools. + +.Master Configuration Using `*GitHubIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: github <1> + challenge: false <2> + login: true <3> + provider: + apiVersion: v1 + kind: GitHubIdentityProvider + clientID: ... <4> + clientSecret: ... <5> +---- +<1> This provider name is prefixed to the GitHub numeric user ID to form an identity name. It is also used to build the callback URL. +<2> `*GitHubIdentityProvider*` cannot be used to send `WWW-Authenticate` challenges. +<3> When `true`, unauthenticated token requests from web clients (like the Management Console) are redirected to GitHub to log in. +<4> The client ID of a link:https://github.com/settings/applications/new[registered GitHub OAuth application]. The application must be configured with a callback URL of `__/oauth2callback/__`. +<5> The client secret issued by GitHub. +==== + +=== Google [[Google]] + +Set `*GoogleIdentityProvider*` in the `*identityProviders*` stanza to use Google as +an identity provider, using +https://developers.google.com/identity/protocols/OpenIDConnect[Google's OpenID +Connect integration]. + +NOTE: Using Google as an identity provider requires users to get a token using +`__/oauth/token/request` to use with command-line tools. + +.Master Configuration Using `*GoogleIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: google <1> + challenge: false <2> + login: true <3> + provider: + apiVersion: v1 + kind: GoogleIdentityProvider + clientID: ... <4> + clientSecret: ... <5> +---- +<1> This provider name is prefixed to the Google numeric user ID to form an identity name. It is also used to build the redirect URL. +<2> `*GoogleIdentityProvider*` cannot be used to send `WWW-Authenticate` challenges. +<3> When `true`, unauthenticated token requests from web clients (like the Management Console) are redirected to Google to log in. +<4> The client ID of a link:https://console.developers.google.com/[registered Google project]. The project must be configured with a redirect URI of `__/oauth2callback/__`. +<5> The client secret issued by Google. +==== + +=== OpenID Connect [[OpenID]] + +Set `*OpenIDIdentityProvider*` in the `*identityProviders*` stanza to integrate with +an OpenID Connect identity provider using an +link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]. + +NOTE: *ID Token* and *UserInfo* decryptions are not supported. + +By default, the `*openid*` scope is requested. If required, extra scopes can be +specified in the `*extraScopes*` field. + +Claims are read from the JWT `id_token` returned from the OpenID identity +provider and, if specified, from the JSON returned by the `*UserInfo*` URL. + +At least one claim must be configured to use as the user's identity. The +link:http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard +identity claim] is `sub`. + +You can also indicate which claims to use as the user's preferred user name, +display name, and email address. If multiple claims are specified, the first one +with a non-empty value is used. The +link:http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard +claims] are: + +[horizontal] +`sub`:: The user identity. +`preferred_username`:: The preferred user name when provisioning a user. +`email`:: Email address. +`name`:: Display name. + +NOTE: Using an OpenID Connect identity provider requires users to get a token using `__/oauth/token/request` to use with command-line tools. + +.Standard Master Configuration Using `*OpenIDIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: my_openid_connect <1> + challenge: false <2> + login: true <3> + provider: + apiVersion: v1 + kind: OpenIDIdentityProvider + clientID: ... <4> + clientSecret: ... <5> + claims: + id: + - sub <6> + preferredUsername: + - preferred_username + name: + - name + email: + - email + urls: + authorize: https://myidp.example.com/oauth2/authorize <7> + token: https://myidp.example.com/oauth2/token <8> +---- +<1> This provider name is prefixed to the value of the identity claim to form an identity name. It is also used to build the redirect URL. +<2> `*OpenIDIdentityProvider*` cannot be used to send `WWW-Authenticate` challenges. +<3> When `true`, unauthenticated token requests from web clients (like the Management Console) are redirected to the authorize URL to log in. +<4> The client ID of a client registered with the OpenID provider. The client must be allowed to redirect to `__/oauth2callback/__`. +<5> The client secret. +<6> Use the value of the `sub` claim in the returned `id_token` as the user's identity. +<7> link:http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] described in the OpenID spec. Must use `https`. +<8> link:http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] described in the OpenID spec. Must use `https`. +==== + +A custom certificate bundle, extra scopes, and `*userInfo*` URL can also be specified: + +.Full Master Configuration Using `*OpenIDIdentityProvider*` +==== + +---- +oauthConfig: + ... + identityProviders: + - name: my_openid_connect + challenge: false + login: true + provider: + apiVersion: v1 + kind: OpenIDIdentityProvider + clientID: ... + clientSecret: ... + ca: my-openid-ca-bundle.crt <1> + extraScopes: <2> + - email + - profile + claims: + id: <3> + - custom_id_claim + - sub + preferredUsername: <4> + - preferred_username + - email + name: <5> + - nickname + - given_name + - name + email: <6> + - custom_email_claim + - email + urls: + authorize: https://myidp.example.com/oauth2/authorize + token: https://myidp.example.com/oauth2/token + userInfo: https://myidp.example.com/oauth2/userinfo <7> +---- +<1> Certificate bundle to use to validate server certificates for the configured URLs. If empty, system trusted roots are used. +<2> List of scopes to request, in addition to the `openid` scope, during the authorization request. +<3> List of claims to use as the identity. First non-empty claim is used. At least one claim is required. If none of the listed claims have a value, authentication fails. +<4> List of claims to use as the preferred user name when provisioning a user for this identity. First non-empty claim is used. +<5> List of claims to use as the display name. First non-empty claim is used. +<6> List of claims to use as the email address. First non-empty claim is used. +<7> link:http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] described in the OpenID spec. Must use `https`. +==== + +== Token Options + +The OAuth server generates two kinds of tokens: + +[horizontal] +Access tokens:: Longer-lived tokens that grant access to the API. +Authorize codes:: Short-lived tokens whose only use is to be exchanged for +an access token. + +Use the `*tokenConfig*` stanza to set token options: + +.Master Configuration Token Options +==== + +---- +oauthConfig: + ... + tokenConfig: + accessTokenMaxAgeSeconds: 86400 <1> + authorizeTokenMaxAgeSeconds: 300 <2> +---- +<1> Set `*accessTokenMaxAgeSeconds*` to control the lifetime of access tokens. +The default lifetime is 24 hours. +<2> Set `*authorizeTokenMaxAgeSeconds*` to control the lifetime of authorize +codes. The default lifetime is five minutes. +==== + +== Grant Options + +To configure how the OAuth server responds to token requests for a client the +user has not previously granted permission, set the `*method*` value in the +`*grantConfig*` stanza. Valid values for `*method*` are: + +[horizontal] +`auto`:: Auto-approve the grant and retry the request. +`prompt`:: Prompt the user to approve or deny the grant. +`deny`:: Auto-deny the grant and return a failure error to the client. + +.Master Configuration Grant Options +==== + +---- +oauthConfig: + ... + grantConfig: + method: auto +---- +==== + +== Session Options + +The OAuth server uses a signed and encrypted cookie-based session during login +and redirect flows. + +Use the `*sessionConfig*` stanza to set session options: + +.Master Configuration Session Options +==== + +---- +oauthConfig: + ... + sessionConfig: + sessionMaxAgeSeconds: 300 <1> + sessionName: ssn <2> + sessionSecretsFile: "..." <3> +---- +<1> Controls the maximum age of a session; sessions auto-expire once a token request is complete. If link:#grant-options[auto-grant] is not enabled, sessions must last as long as the user is expected to take to approve or reject a client authorization request. +<2> Name of the cookie used to store the session. +<3> File name containing serialized `*SessionSecrets*` object. If empty, a random signing and encryption secret is generated at each server start. +==== + +If no `*sessionSecretsFile*` is specified, a random signing and encryption +secret is generated at each start of the master server. This means that any +logins in progress will have their sessions invalidated if the master is +restarted. It also means that if multiple masters are configured, they will not +be able to decode sessions generated by one of the other masters. + +To specify the signing and encryption secret to use, specify a +`*sessionSecretsFile*`. This allows you separate secret values from the +configuration file and keep the configuration file distributable, for example +for debugging purposes. + +Multiple secrets can be specified in the `*sessionSecretsFile*` to enable +rotation. New sessions are signed and encrypted using the first secret in the +list. Existing sessions are decrypted and authenticated by each secret until one +succeeds. + +.Session Secret Configuration: +==== + +---- +apiVersion: v1 +kind: SessionSecrets +secrets: <1> +- authentication: "..." <2> + encryption: "..." <3> +- authentication: "..." + encryption: "..." +... +---- +<1> List of secrets used to authenticate and encrypt cookie sessions. At least one secret must be specified. Each secret must set an authentication and encryption secret. +<2> Signing secret, used to authenticate sessions using HMAC. Recommended to use a secret with 32 or 64 bytes. +<3> Encrypting secret, used to encrypt sessions. Must be 16, 24, or 32 characters long, to select AES-128, AES-192, or AES-256. +==== diff --git a/dev_guide/master_node_configuration.adoc b/admin_guide/master_node_configuration.adoc similarity index 100% rename from dev_guide/master_node_configuration.adoc rename to admin_guide/master_node_configuration.adoc diff --git a/architecture/additional_concepts/authentication.adoc b/architecture/additional_concepts/authentication.adoc index 4c62273b3460..7ed5ca01e26b 100644 --- a/architecture/additional_concepts/authentication.adoc +++ b/architecture/additional_concepts/authentication.adoc @@ -5,50 +5,76 @@ :icons: :experimental: :toc: macro -:toc-title: +:toc-title: toc::[] == Overview +The authentication layer identifies the user associated with requests to the +OpenShift API. The authorization layer then uses information about the +requesting user to determine if the request should be allowed. -The authentication layer is responsible for identifying the user associated with requests to the OpenShift API. Information about the requesting user is then used by the authorization layer to determine whether the request should be allowed. +As an administrator, you can link:../../admin_guide/configuring_authentication.html[configure authentication] using a +link:../../admin_guide/master_node_configuration.html[master configuration file]. == API Authentication - Requests to the OpenShift API are authenticated using the following methods: -* OAuth Access Tokens -** Obtained from the OpenShift OAuth server using the `/oauth/authorize` and `/oauth/token` endpoints -** Sent as an "Authorization: Bearer …" header or an "access_token=…" query parameter -* X.509 Client Certificates -** Requires a https connection to the API server -** Verified by the API server against a trusted certificate authority bundle -** The API server creates and distributes certificates to controllers to authenticate themselves +OAuth Access Tokens:: +- Obtained from the OpenShift OAuth server using the `__/oauth/authorize` and `__/oauth/token` endpoints. +- Sent as an `Authorization: Bearer...` header or an `access_token=...` query parameter + +X.509 Client Certificates:: +* Requires a HTTPS connection to the API server. +* Verified by the API server against a trusted certificate authority bundle. +* The API server creates and distributes certificates to controllers to authenticate themselves. + +Any request with an invalid access token or an invalid certificate is rejected +by the authentication layer with a 401 error. + +If no access token or certificate is presented, the authentication layer assigns +the `system:anonymous` user and the `system:unauthenticated` group to the +request. This allows the authorization layer to determine which requests,if any, +an anonymous user is allowed to make. -Any request with an invalid access token or an invalid certificate is rejected by the authentication layer with a 401 error. +== OAuth +The OpenShift master includes a built-in OAuth server. End-users obtain OAuth +access tokens to authenticate themselves to the API. -If no access token or certificate is presented, the authentication layer assigns the `system:anonymous` user and the `system:unauthenticated` group to the request. This allows the authorization layer to determine which requests (if any) an anonymous user is allowed to make. +When a person requests a new OAuth token, the OAuth server uses the configured +link:../../admin_guide/configuring_authentication.html[identity +provider] to determine the identity of the person making the request. -== OAuth overview +It then determines what user that identity maps to, creates an access token for +that user, and returns the token for use. -The OpenShift master includes a built-in OAuth server. End-users obtain OAuth access tokens to authenticate themselves to the API. +*OAuth Clients* [[oauth-clients]] -When a person requests a new OAuth token, the OAuth server uses the configured identity provider(s) to determine the identity of the person making the request. +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 API: -It then determines what user that identity maps to, creates an access token for that user, and returns the token for use. +|=== -=== OAuth clients +|OAuth Client |Usage -Every request for an OAuth token must specify the OAuth client which will receive and use the token. The following OAuth clients are automatically created when starting the OpenShift API: +|*openshift-web-console* +|Requests tokens for the Management Console. - * `openshift-web-console`: used to request tokens for the web console - * `openshift-browser-client`: used to request tokens at `/oauth/token/request` with a user-agent that can handle interactive logins - * `openshift-challenging-client`: used to request tokens with a user-agent that can handle `WWW-Authenticate` challenges +|*openshift-browser-client* +|Requests tokens at `__/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: + ==== + ---- -osc create -f <(echo ' +$ osc create -f <(echo ' { "kind": "OAuthClient", "version": "v1beta1", @@ -61,417 +87,31 @@ osc create -f <(echo ' ] }') ---- -<1> The `name` of the OAuth client is used as the `client_id` parameter when making requests to `/oauth/authorize` and `/oauth/token`. -<2> The `secret` is used as the `client_secret` parameter when making requests to `/oauth/token`. -<3> The `redirect_uri` parameter specified in requests to `/oauth/authorize` and `/oauth/token` must be equal to (or prefixed by) one of the URIs in `redirectURIs`. -==== - -=== Integrations - -All requests for OAuth tokens involve a request to `/oauth/authorize`. Most authentication integrations will place an authenticating proxy in front of this endpoint, or configure OpenShift to validate credentials against a backing identity provider. - -Because requests to `/oauth/authorize` can come from user-agents that cannot display interactive login pages (like `osc`), authenticating using a `WWW-Authenticate` challenge is supported in addition to interactive login flows. - -If an authenticating proxy is placed in front of the `/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. - -If the authenticating proxy cannot support `WWW-Authenticate` challenges (or if OpenShift is configured to use an identity provider that does not support WWW-Authenticate challenges), users can visit `/oauth/token/request` using a browser to obtain an access token manually. - -== OAuth configuration - -OAuth configuration is specified in the master config file. - -When running without a master config file, the `AllowAllPasswordIdentityProvider` identity provider is used, which allows any non-empty username and password to log in. This is useful for test purposes. - -To use other identity providers, you must run from a config file. For more information about creating and running from config files, see link:../../dev_guide/master_node_configuration.html[Master and Node Configuration]. - -=== Identity providers - -==== Allow All [[AllowAllPasswordIdentityProvider]] - -`AllowAllPasswordIdentityProvider` allows any non-empty login and password. This is the default identity provider when running OpenShift without a config file. - -Master config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: my_allow_provider <1> - challenge: true <2> - login: true <3> - provider: - apiVersion: v1 - kind: AllowAllPasswordIdentityProvider ----- -<1> This provider name is prefixed to logins to form an identity name. -<2> When `true`, unauthenticated token requests from non-web clients (like `osc`) will be sent a WWW-Authenticate challenge header for this provider. -<3> When `true`, unauthenticated token requests from web clients (like the web console) will be redirected to a login page backed by this provider. -==== - -==== Deny All [[DenyAllPasswordIdentityProvider]] - -`DenyAllPasswordIdentityProvider` denies all username and passwords. - -Master config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: my_deny_provider <1> - challenge: true <2> - login: true <3> - provider: - apiVersion: v1 - kind: DenyAllPasswordIdentityProvider ----- -<1> This provider name is prefixed to logins to form an identity name. -<2> When `true`, unauthenticated token requests from non-web clients (like `osc`) will be sent a WWW-Authenticate challenge header for this provider. -<3> When `true`, unauthenticated token requests from web clients (like the web console) will be redirected to a login page backed by this provider. -==== - -==== HTPasswd [[HTPasswdPasswordIdentityProvider]] - -`HTPasswdPasswordIdentityProvider` validates logins and passwords against a flat-file generated using http://httpd.apache.org/docs/2.4/programs/htpasswd.html[htpasswd] - -* Only MD5 and SHA encryption types are supported. MD5 encryption is recommended, and is the default for htpasswd. Plaintext, crypt, and bcrypt hashes are not currently supported. -* The file is re-read if its modification time changes, without requiring a server restart -* To create the file: `htpasswd -c ` -* To add or update a login to the file: `htpasswd ` -* To remove a login from the file: `htpasswd -D ` - -Master config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: my_htpasswd_provider <1> - challenge: true <2> - login: true <3> - provider: - apiVersion: v1 - kind: HTPasswdPasswordIdentityProvider - file: /path/to/users.htpasswd <4> ----- -<1> This provider name is prefixed to logins to form an identity name. -<2> When `true`, unauthenticated token requests from non-web clients (like `osc`) will be sent a WWW-Authenticate challenge header for this provider. -<3> When `true`, unauthenticated token requests from web clients (like the web console) will be redirected to a login page backed by this provider. -<4> File generated using http://httpd.apache.org/docs/2.4/programs/htpasswd.html[htpasswd]. -==== - -==== Basic-Auth (remote) [[BasicAuthPasswordIdentityProvider]] - -`BasicAuthPasswordIdentityProvider` validates logins and passwords against a remote server using a server-to-server basic-auth request. - -* Logins and passwords are validated against a basic-auth protected, JSON-returning remote URL -* A 401 response indicates failed auth. -* A non-200 status, or the presence of a non-empty "error" key, indicates an error: `{"error":"Error message"}` -* A 200 status with an "sub" key (subject) indicates success: `{"sub":"userid"}` -** The subject must be unique to the authenticated user -** The subject must not be able to be modified -* A successful response may optionally provide additional data: -** Display name using the `name` key. Example: `{"sub":"userid", "name": "User Name", ...}` -** Email address using the `email` key. Example: `{"sub":"userid", "email":"user@example.com", ...}` -** Preferred username using the `preferred_username` key. This is useful when the unique, unchangeable subject is a database key or UID, and a more human-readable name exists. This is used as a hint when provisioning the OpenShift user for the authenticated identity. Example: `{"sub":"014fbff9a07c", "preferred_username":"bob", ...}` - -Master config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: my_remote_basic_auth_provider <1> - challenge: true <2> - login: true <3> - provider: - apiVersion: v1 - kind: BasicAuthPasswordIdentityProvider - url: https://www.example.com/remote-idp <4> - ca: /path/to/ca.file <5> - certFile: /path/to/client.crt <6> - keyFile: /path/to/client.key <7> ----- -<1> This provider name is prefixed to the returned user id to form an identity name. -<2> When `true`, unauthenticated token requests from non-web clients (like `osc`) will be sent a WWW-Authenticate challenge header for this provider. -<3> When `true`, unauthenticated token requests from web clients (like the web console) will be redirected to a login page backed by this provider. -<4> URL accepting credentials in basic-auth headers. -<5> Certificate bundle to use to validate server certificates for the configured URL. Optional. -<6> Client certificate to present when making requests to the configured URL. Optional. -<7> Key for the client certificate. Required if `certFile` is specified. -==== - -==== Request Header [[RequestHeaderIdentityProvider]] - -`RequestHeaderIdentityProvider` identifies users from request header values, like `X-Remote-User`. It is typically used in combination with an authenticating proxy, which sets the request header value. - -Master config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: my_request_header_provider <1> - challenge: false <2> - login: false <3> - provider: - apiVersion: v1 - kind: RequestHeaderIdentityProvider - clientCA: /path/to/client-ca.file <4> - headers: <5> - - X-Remote-User - - SSO-User ----- -<1> This provider name is prefixed to the user id in the request header to form an identity name. -<2> `RequestHeaderIdentityProvider` cannot be used to send WWW-Authenticate challenges. -<3> `RequestHeaderIdentityProvider` cannot be used to back a login page. -<4> PEM-encoded certificate bundle. If set, a valid client certificate must be presented and validated against the certificate authorities in the specified file before the request headers are checked for usernames. Optional. -<5> Header names to check, in order, for user ids. The first header containing a value is used as the user id. Required, case-insensitive. -==== - -==== GitHub [[GitHub]] - -`GitHubIdentityProvider` uses GitHub as an identity provider, using the OAuth integration. - -Note that using GitHub as an identity provider requires users to get a token using `/oauth/token/request` to use with command-line tools. - -Master config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: github <1> - challenge: false <2> - login: true <3> - provider: - apiVersion: v1 - kind: GitHubIdentityProvider - clientID: ... <4> - clientSecret: ... <5> ----- -<1> This provider name is prefixed to the GitHub numeric user id to form an identity name. It is also used to build the callback URL. -<2> `GitHubIdentityProvider` cannot be used to send WWW-Authenticate challenges. -<3> When `true`, unauthenticated token requests from web clients (like the web console) will be redirected to GitHub to log in. -<4> The client id of a link:https://github.com/settings/applications/new[registered GitHub OAuth application]. The application must be configured with a callback URL of `/oauth2callback/` -<5> The client secret issued by GitHub. -==== - -==== Google [[Google]] - -`GoogleIdentityProvider` uses Google as an identity provider, using Google's OpenID Connect integration. - -See https://developers.google.com/identity/protocols/OpenIDConnect for more information. - -Note that using Google as an identity provider requires users to get a token using `/oauth/token/request` to use with command-line tools. - -Master config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: google <1> - challenge: false <2> - login: true <3> - provider: - apiVersion: v1 - kind: GoogleIdentityProvider - clientID: ... <4> - clientSecret: ... <5> - hostedDomain: "" <6> ----- -<1> This provider name is prefixed to the Google numeric user id to form an identity name. It is also used to build the redirect URL. -<2> `GoogleIdentityProvider` cannot be used to send WWW-Authenticate challenges. -<3> When `true`, unauthenticated token requests from web clients (like the web console) will be redirected to Google to log in. -<4> The client id of a link:https://console.developers.google.com/[registered Google project]. The project must be configured with a redirect URI of `/oauth2callback/` -<5> The client secret issued by Google. -<6> Optional link:https://developers.google.com/identity/protocols/OpenIDConnect#hd-param[hosted domain] to restrict sign-in accounts to. If empty, any Google account is allowed to authenticate. +<1> The `name` of the OAuth client is used as the `client_id` parameter when making requests to `__/oauth/authorize` and `__/oauth/token`. +<2> The `secret` is used as the `client_secret` parameter when making requests to `__/oauth/token`. +<3> The `redirect_uri` parameter specified in requests to `__/oauth/authorize` and `__/oauth/token` must be equal to (or prefixed by) one of the URIs in `redirectURIs`. ==== -==== OpenID Connect [[OpenID]] +*Integrations* [[integrations]] -`OpenIDIdentityProvider` integrates with an OpenID Connect identity provider, using an link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]. +All requests for OAuth tokens involve a request to `__/oauth/authorize`. +Most authentication integrations place an authenticating proxy in front of this +endpoint, or configure OpenShift to validate credentials against a backing +link:../../admin_guide/configuring_authentication.html[identity provider]. -ID Token and UserInfo decryption is not supported. +Requests to `__/oauth/authorize` can come from user-agents that cannot +display interactive login pages, such as the CLI. Therefore, OpenShift supports +authenticating using a `WWW-Authenticate` challenge in addition to interactive +login flows. -By default, the `openid` scope is requested. Extra scopes (if needed) can be specified in the `extraScopes` config field. +If an authenticating proxy is placed in front of the +`__/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. -Claims are read from the JWT `id_token` returned from the OpenID identity provider (and from the JSON returned by the `UserInfo` URL, if specified). - -At least one claim must be configured as the claim to use as the user's identity. The link:http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard identity claim] is `sub`. - -You can also indicate which claims to use as the user's preferred username, display name, and email address. If multiple claims are specified, the first one with a non-empty value is used. The link:http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard claims] are: - -* `sub` (used as the user identity) -* `preferred_username` (used as the preferred user name when provisioning a user) -* `email` (email address) -* `name` (display name) - -Note that using an OpenID Connect identity provider requires users to get a token using `/oauth/token/request` to use with command-line tools. - -Standard config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: my_openid_connect <1> - challenge: false <2> - login: true <3> - provider: - apiVersion: v1 - kind: OpenIDIdentityProvider - clientID: ... <4> - clientSecret: ... <5> - claims: - id: - - sub <6> - preferredUsername: - - preferred_username - name: - - name - email: - - email - urls: - authorize: https://myidp.example.com/oauth2/authorize <7> - token: https://myidp.example.com/oauth2/token <8> ----- -<1> This provider name is prefixed to the value of the identity claim to form an identity name. It is also used to build the redirect URL. -<2> `OpenIDIdentityProvider` cannot be used to send WWW-Authenticate challenges. -<3> When `true`, unauthenticated token requests from web clients (like the web console) will be redirected to the authorize URL to log in. -<4> The client id of a client registered with the OpenID provider. The client must be allowed to redirect to `/oauth2callback/` -<5> The client secret. -<6> Use the value of the `sub` claim in the returned `id_token` as the user's identity. -<7> link:http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] described in the OpenID spec. Must use https. -<8> link:http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] described in the OpenID spec. Must use https. -==== - -A custom certificate bundle, extra scopes, extra authorization request parameters, and UserInfo URL can also be specified. - -Full config: -==== ----- -oauthConfig: - ... - identityProviders: - - name: my_openid_connect - challenge: false - login: true - provider: - apiVersion: v1 - kind: OpenIDIdentityProvider - clientID: ... - clientSecret: ... - ca: my-openid-ca-bundle.crt <1> - extraScopes: <2> - - email - - profile - extraAuthorizeParameters: <3> - include_granted_scopes: "true" - claims: - id: <4> - - custom_id_claim - - sub - preferredUsername: <5> - - preferred_username - - email - name: <6> - - nickname - - given_name - - name - email: <7> - - custom_email_claim - - email - urls: - authorize: https://myidp.example.com/oauth2/authorize - token: https://myidp.example.com/oauth2/token - userInfo: https://myidp.example.com/oauth2/userinfo <8> ----- -<1> Certificate bundle to use to validate server certificates for the configured URLs. If empty, system trusted roots are used. -<2> Optional list of scopes to request (in addition to the `openid` scope) during the authorization token request. -<3> Optional map of extra parameters to add to the authorization token request. -<4> List of claims to use as the identity. First non-empty claim is used. At least one claim is required. If none of the listed claims have a value, authentication will fail. -<5> List of claims to use as the preferred username when provisioning a user for this identity. First non-empty claim is used. -<6> List of claims to use as the display name. First non-empty claim is used. -<7> List of claims to use as the email address. First non-empty claim is used. -<8> link:http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] described in the OpenID spec. Must use https. -==== - -=== Token options - -The OAuth server generates two kinds of tokens. - -Authorize codes are short-lived tokens whose only use is to be exchanged for an access token. Set `authorizeTokenMaxAgeSeconds` to control the lifetime of authorize codes. The default lifetime is 5 minutes. - -Access tokens are longer-lived tokens that grant access to the API. Set `accessTokenMaxAgeSeconds` to control the lifetime of access tokens. The default lifetime is 24 hours. - -Master config: ----- -oauthConfig: - ... - tokenConfig: - accessTokenMaxAgeSeconds: 86400 - authorizeTokenMaxAgeSeconds: 300 ----- - -=== Grant options - -To configure how the OAuth server responds to token requests for a client the user has not previously granted permission, set the `method` value in the `grantConfig` stanza. Valid values are: - -* `auto` -** Auto-approve the grant and retry the request -* `prompt` -** Prompt the user to approve or deny the grant -* `deny` -** Auto-deny the grant and return a failure error to the client - -Master config: ----- -oauthConfig: - ... - grantConfig: - method: auto ----- - -=== Session options - -The OAuth server uses a signed and encrypted cookie-based session during login and redirect flows. - -If no `sessionSecretsFile` is specified, a random signing and encryption secret is generated at each start of the master server. This means that any logins in progress will have their sessions invalidated if the master is restarted. It also means that if multiple masters are configured, they will not be able to decode sessions generated by one of the other masters. - -To specify the signing and encryption secret to use, specify a `sessionSecretsFile`. This allows you separate secret values from the config file, and keep the config file distributable for debugging, etc. - -Master config: -==== ----- -oauthConfig: - ... - sessionConfig: - sessionMaxAgeSeconds: 300 <1> - sessionName: ssn <2> - sessionSecretsFile: "..." <3> ----- -<1> Controls the maximum age of a session (sessions auto-expire once a token request is complete). If auto-grant is not enabled, sessions must last as long as the user is expected to take to approve or reject a client authorization request. -<2> Name of the cookie used to store the session. -<3> Filename containing serialized SessionSecrets object. If empty, a random signing and encryption secret is generated at each server start. -==== - -Multiple secrets can be specified in the `sessionSecretsFile` to enable rotation. New sessions are signed and encrypted using the first secret in the list. Existing sessions are decrypted/authenticated by each secret until one succeeds. - -Session secret config: -==== ----- -apiVersion: v1 -kind: SessionSecrets -secrets: <1> -- authentication: "..." <2> - encryption: "..." <3> -- authentication: "..." - encryption: "..." -... ----- -<1> List of secrets used to authenticate and encrypt cookie sessions. At least one secret must be specified. Each secret must set an authentication and encryption secret. -<2> Signing secret, used to authenticate sessions using HMAC. Recommended to use a secret with 32 or 64 bytes. -<3> Encrypting secret, used to encrypt sessions. Must be 16, 24, or 32 characters long, to select AES-128, AES-192, or AES-256. -==== \ No newline at end of file +If the authenticating proxy cannot support `WWW-Authenticate` challenges, or if +OpenShift is configured to use an +link:../../admin_guide/configuring_authentication.html[identity provider] that +does not support WWW-Authenticate challenges, users can visit +`__/oauth/token/request` using a browser to obtain an access token +manually.