diff --git a/_topic_map.yml b/_topic_map.yml index a9150e610b..aed85940be 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -65,6 +65,33 @@ Topics: File: understanding-authentication - Name: Configuring the internal OAuth server File: configuring-internal-oauth +- Name: Understanding identity provider configuration + File: understanding-identity-provider +- Name: Configuring identity providers + Dir: identity_providers + Topics: + - Name: Configuring an allow all identity provider + File: configuring-allow-all-identity-provider + - Name: Configuring a deny all identity provider + File: configuring-deny-all-identity-provider + - Name: Configuring an HTPasswd identity provider + File: configuring-htpasswd-identity-provider + - Name: Configuring a Keystone identity provider + File: configuring-keystone-identity-provider + - Name: Configuring an LDAP identity provider + File: configuring-ldap-identity-provider + - Name: Configuring a basic authentication identity provider + File: configuring-basic-authentication-identity-provider + - Name: Configuring a request header identity provider + File: configuring-request-header-identity-provider + - Name: Configuring a GitHub or GitHub Enterprise identity provider + File: configuring-github-identity-provider + - Name: Configuring a GitLab identity provider + File: configuring-gitlab-identity-provider + - Name: Configuring a Google identity provider + File: configuring-google-identity-provider + - Name: Configuring an OpenID Connect identity provider + File: configuring-oidc-identity-provider - Name: Using RBAC to define and apply permissions File: using-rbac - Name: Configuring LDAP failover diff --git a/authentication/identity_providers/configuring-allow-all-identity-provider.adoc b/authentication/identity_providers/configuring-allow-all-identity-provider.adoc new file mode 100644 index 0000000000..51dcc7892d --- /dev/null +++ b/authentication/identity_providers/configuring-allow-all-identity-provider.adoc @@ -0,0 +1,16 @@ +[id='configuring-allow-all-identity-provider'] += Configuring an allow all identity provider +include::modules/common-attributes.adoc[] +:context: configuring-allow-all-identity-provider +toc::[] + +Configure the `allow-all` identity provider to allow any non-empty user name +and password to log in. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-allow-all-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc b/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc new file mode 100644 index 0000000000..bdc027eb9e --- /dev/null +++ b/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc @@ -0,0 +1,23 @@ +[id='configuring-basic-authentication-identity-provider'] += Configuring an basic authentication identity provider +include::modules/common-attributes.adoc[] +:context: configuring-basic-authentication-identity-provider +toc::[] + +Configure a `basic-authentication` identity provider for users to log in to +{product-title} with credentials validated against a remote identity provider. +Basic authentication is a generic backend integration mechanism. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-about-basic-authentication.adoc[leveloffset=+1] + +include::modules/identity-provider-configuring-basic-authentication.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-basic-authentication-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] + +include::modules/identity-provider-basic-authentication-troubleshooting.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-deny-all-identity-provider.adoc b/authentication/identity_providers/configuring-deny-all-identity-provider.adoc new file mode 100644 index 0000000000..7349dafa45 --- /dev/null +++ b/authentication/identity_providers/configuring-deny-all-identity-provider.adoc @@ -0,0 +1,16 @@ +[id='configuring-deny-all-identity-provider'] += Configuring a deny all identity provider +include::modules/common-attributes.adoc[] +:context: configuring-deny-all-identity-provider +toc::[] + +Configure the `deny-all` identity provider to deny access for all user names and +passwords. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-deny-all-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-github-identity-provider.adoc b/authentication/identity_providers/configuring-github-identity-provider.adoc new file mode 100644 index 0000000000..cca53901f6 --- /dev/null +++ b/authentication/identity_providers/configuring-github-identity-provider.adoc @@ -0,0 +1,38 @@ +[id='configuring-github-identity-provider'] += Configuring a GitHub or GitHub Enterprise identity provider +include::modules/common-attributes.adoc[] +:context: configuring-github-identity-provider +toc::[] + +Configure a `github` identity provider to validate user names and passwords +against GitHub or GitHub Enterprise's OAuth authentication server. OAuth +facilitates a token exchange flow between +{product-title} and GitHub or GitHub Enterprise. + +You can use the GitHub integration to connect to either GitHub or GitHub +Enterprise. For GitHub Enterprise integrations, you must provide the `hostname` +of your instance and can optionally provide a `ca` certificate bundle to use in +requests to the server. + +[NOTE] +==== +The following steps apply to both GitHub and GitHub Enterprise unless noted. +==== + +Configuring GitHub authentication allows users to log in to {product-title} with +their GitHub credentials. To prevent anyone with any GitHub user ID from logging +in to your {product-title} cluster, you can restrict access to only those in +specific GitHub organizations. + + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-registering-github.adoc[leveloffset=+1] + +include::modules/identity-provider-configuring-github.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-github-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-gitlab-identity-provider.adoc b/authentication/identity_providers/configuring-gitlab-identity-provider.adoc new file mode 100644 index 0000000000..1f17cbdae4 --- /dev/null +++ b/authentication/identity_providers/configuring-gitlab-identity-provider.adoc @@ -0,0 +1,22 @@ +[id='configuring-gitlab-identity-provider'] += Configuring a GitLab identity provider +include::modules/common-attributes.adoc[] +:context: configuring-gitlab-identity-provider +toc::[] + +Configure a `gitlab` identity provider to use +link:https://gitlab.com/[GitLab.com] or any other GitLab instance as an identity +provider. If you use GitLab version 7.7.0 to 11.0, you connect using the +link:http://doc.gitlab.com/ce/integration/oauth_provider.html[OAuth integration]. +If you use GitLab version 11.1 or later, you can use +link:https://docs.gitlab.com/ce/integration/openid_connect_provider.html[OpenID Connect] (OIDC) +to connect instead of OAuth. + + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-gitlab-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-google-identity-provider.adoc b/authentication/identity_providers/configuring-google-identity-provider.adoc new file mode 100644 index 0000000000..7e49be5879 --- /dev/null +++ b/authentication/identity_providers/configuring-google-identity-provider.adoc @@ -0,0 +1,29 @@ +[id='configuring-google-identity-provider'] += Configuring a Google identity provider +include::modules/common-attributes.adoc[] +:context: configuring-google-identity-provider +toc::[] + +Configure a `google` identity provider using +link: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. +==== + +[WARNING] +==== +Using Google as an identity provider allows any Google user to authenticate to your server. +You can limit authentication to members of a specific hosted domain with the +`hostedDomain` configuration attribute. +==== + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-google-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-htpasswd-identity-provider.adoc b/authentication/identity_providers/configuring-htpasswd-identity-provider.adoc new file mode 100644 index 0000000000..db5fd53e7c --- /dev/null +++ b/authentication/identity_providers/configuring-htpasswd-identity-provider.adoc @@ -0,0 +1,19 @@ +[id='configuring-htpasswd-identity-provider'] += Configuring an HTPasswd identity provider +include::modules/common-attributes.adoc[] +:context: configuring-htpasswd-identity-provider +toc::[] + +Configure the `htpasswd` identity provider to validate user names and passwords +against a flat file generated using +link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-creating-htpasswd-file.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-htpasswd-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-keystone-identity-provider.adoc b/authentication/identity_providers/configuring-keystone-identity-provider.adoc new file mode 100644 index 0000000000..1f264284a3 --- /dev/null +++ b/authentication/identity_providers/configuring-keystone-identity-provider.adoc @@ -0,0 +1,31 @@ +[id='configuring-keystone-identity-provider'] += Configuring a Keystone identity provider +include::modules/common-attributes.adoc[] +:context: configuring-keystone-identity-provider +toc::[] + +Configure the `keystone` identity provider to integrate +your {product-title} cluster with Keystone to enable shared authentication with +an OpenStack Keystone v3 server configured to store users in an internal +database. This configuration allows users to log in to {product-title} with +their Keystone credentials. + +http://docs.openstack.org/developer/keystone/[Keystone] is an OpenStack project +that provides identity, token, catalog, and policy services. + +You can configure the integration with Keystone so that the new {product-title} +users are based on either the Keystone user names or unique Keystone IDs. +With both methods, users log in by entering their Keystone user name and +password. Basing the {product-title} users off of the Keystone ID is more +secure. If you delete a Keystone user and create a new Keystone user with that +user name, the new user might have access to the old user's resources. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-configuring-keystone.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-keystone-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-ldap-identity-provider.adoc b/authentication/identity_providers/configuring-ldap-identity-provider.adoc new file mode 100644 index 0000000000..fe63caad32 --- /dev/null +++ b/authentication/identity_providers/configuring-ldap-identity-provider.adoc @@ -0,0 +1,18 @@ +[id='configuring-ldap-identity-provider'] += Configuring an LDAP identity provider +include::modules/common-attributes.adoc[] +:context: configuring-ldap-identity-provider +toc::[] + +Configure the `ldap` identity provider to validate user names and passwords +against an LDAPv3 server, using simple bind authentication. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-about-ldap.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-ldap-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-oidc-identity-provider.adoc b/authentication/identity_providers/configuring-oidc-identity-provider.adoc new file mode 100644 index 0000000000..ac8e1af73c --- /dev/null +++ b/authentication/identity_providers/configuring-oidc-identity-provider.adoc @@ -0,0 +1,66 @@ +[id='configuring-oidc-identity-provider'] += Configuring a OpenID Connect identity provider +include::modules/common-attributes.adoc[] +:context: configuring-oidc-identity-provider +toc::[] + +Configure an `oidc` identity provider 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]. + +ifdef::openshift-origin[] +You can link:https://www.keycloak.org/docs/latest/server_admin/index.html#openshift[configure a Keycloak] server as an OpenID +Connect identity provider for {product-title}. +endif::[] + +ifdef::openshift-enterprise[] +You can +link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html/red_hat_single_sign-on_for_openshift/tutorials[configure Red Hat Single Sign-On] +as an OpenID Connect identity provider for {product-title}. +endif::[] + +[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 +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 standard claims are: + +[horizontal] +`sub`:: Short for "subject identifier." The remote identity for the user at the +issuer. +`preferred_username`:: The preferred user name when provisioning a user. A +shorthand name that the user wants to be referred to as, such as `janedoe`. Typically +a value that corresponding to the user's login or username in the authentication +system, such as username or email. +`email`:: Email address. +`name`:: Display name. + +See the +link:http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[OpenID claims documentation] +for more information. + +[NOTE] +==== +Using an OpenID Connect identity provider requires users to get a token using +`/oauth/token/request` to use with command-line tools. +==== + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-oidc-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-request-header-identity-provider.adoc b/authentication/identity_providers/configuring-request-header-identity-provider.adoc new file mode 100644 index 0000000000..156ff45383 --- /dev/null +++ b/authentication/identity_providers/configuring-request-header-identity-provider.adoc @@ -0,0 +1,19 @@ +[id='configuring-request-header-identity-provider'] += Configuring a request header identity provider +include::modules/common-attributes.adoc[] +:context: configuring-request-header-identity-provider +toc::[] + +Configure a `request-header` identity provider 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. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +include::modules/identity-provider-about-request-header.adoc[leveloffset=+1] + +include::modules/identity-provider-create-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-request-header-CRD.adoc[leveloffset=+1] + +include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/understanding-identity-provider.adoc b/authentication/understanding-identity-provider.adoc new file mode 100644 index 0000000000..101b55a5a5 --- /dev/null +++ b/authentication/understanding-identity-provider.adoc @@ -0,0 +1,82 @@ +[id='understanding-identity-provider'] += Understanding identity provider configuration +include::modules/common-attributes.adoc[] +:context: understanding-identity-provider +toc::[] + +The {product-title} master includes a built-in OAuth server. Developers and +administrators obtain OAuth access tokens to authenticate themselves to the API. + +As an administrator, you can configure OAuth to specify an identity provider +after you install your cluster. + +include::modules/identity-provider-overview.adoc[leveloffset=+1] + +[id='supported-identity-providers'] +== Supported identity providers + +You can configure the following types of identity providers: + +[cols="2a,8a",options="header"] +|=== + +|Identity provider +|Description + +|xref:../authentication/identity_providers/configuring-allow-all-identity-provider.adoc#configuring-allow-all-identity-provider[Allow all] +|Configure the `allow-all` identity provider to allow any non-empty user name +and password to log in. + +|xref:../authentication/identity_providers/configuring-deny-all-identity-provider.adoc#configuring-deny-all-identity-provider[Deny all] +|Configure the `deny-all` identity provider to deny access for all user names and +passwords. + +|xref:../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#configuring-htpasswd-identity-provider[HTPasswd] +|Configure the `htpasswd` identity provider to validate user names and passwords +against a flat file generated using +link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. + +|xref:../authentication/identity_providers/configuring-keystone-identity-provider.adoc#configuring-keystone-identity-provider[Keystone] +|Configure the `keystone` identity provider to integrate +your {product-title} cluster with Keystone to enable shared authentication with +an OpenStack Keystone v3 server configured to store users in an internal +database. + +|xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[LDAP] +|Configure the `ldap` identity provider to validate user names and passwords +against an LDAPv3 server, using simple bind authentication. + +|xref:../authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc#configuring-basic-authentication-identity-provider[Basic authentication] +|Configure a `basic-authentication` identity provider for users to log in to +{product-title} with credentials validated against a remote identity provider. +Basic authentication is a generic backend integration mechanism. + +|xref:../authentication/identity_providers/configuring-request-header-identity-provider.adoc#configuring-request-header-identity-provider[Request header] +|Configure a `request-header` identity provider 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. + +|xref:../authentication/identity_providers/configuring-github-identity-provider.adoc#configuring-github-identity-provider[GitHub or GitHub Enterprise] +|Configure a `github` identity provider to validate user names and passwords +against GitHub or GitHub Enterprise's OAuth authentication server. + +|xref:../authentication/identity_providers/configuring-gitlab-identity-provider.adoc#configuring-gitlab-identity-provider[GitLab] +|Configure a `gitlab` identity provider to use +link:https://gitlab.com/[GitLab.com] or any other GitLab instance as an identity +provider. + +|xref:../authentication/identity_providers/configuring-google-identity-provider.adoc#configuring-google-identity-provider[Google] +|Configure a `google` identity provider using +link:https://developers.google.com/identity/protocols/OpenIDConnect[Google's OpenID Connect integration]. + +|xref:../authentication/identity_providers/configuring-oidc-identity-provider.adoc#configuring-oidc-identity-provider[OpenID Connect] +|Configure an `oidc` identity provider 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]. + +|=== + + +include::modules/identity-provider-parameters.adoc[leveloffset=+1] + +include::modules/identity-provider-default-CRD.adoc[leveloffset=+1] diff --git a/modules/identity-provider-about-basic-authentication.adoc b/modules/identity-provider-about-basic-authentication.adoc new file mode 100644 index 0000000000..d200dddcd1 --- /dev/null +++ b/modules/identity-provider-about-basic-authentication.adoc @@ -0,0 +1,75 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc + +[id='identity-provider-about-basic-authentication-{context}'] += About basic authentication + +Basic authentication is a generic backend integration mechanism that allows +users to log in to {product-title} with credentials validated against a remote +identity provider. + +Because basic authentication is generic, you can use this identity +provider for advanced authentication configurations. + +[CAUTION] +==== +Basic authentication must use an HTTPS connection to the remote server to +prevent potential snooping of the user ID and password and man-in-the-middle +attacks. +==== + +With basic authentication configured, users send their user name +and password to {product-title}, which then validates those credentials against +a remote server by making a server-to-server request, passing the credentials as +a basic authentication header. This requires users to send their credentials to +{product-title} during login. + +[NOTE] +==== +This only works for user name/password login mechanisms, and {product-title} must +be able to make network requests to the remote authentication server. +==== + +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 can 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 +{product-title} user for the authenticated identity. For example: ++ +---- +{"sub":"014fbff9a07c", "preferred_username":"bob", ...} +---- diff --git a/modules/identity-provider-about-ldap.adoc b/modules/identity-provider-about-ldap.adoc new file mode 100644 index 0000000000..95a969482e --- /dev/null +++ b/modules/identity-provider-about-ldap.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-ldap-identity-provider.adoc + +[id='identity-provider-about-ldap-{context}'] += About LDAP authentication + +During authentication, the LDAP directory is searched for an entry that matches +the provided user name. If a single unique match is found, a simple bind is +attempted using the distinguished name (DN) of the entry plus the provided +password. + +These are the steps taken: + +. Generate a search filter by combining the attribute and filter in the +configured `url` with the user-provided user name. +. Search the directory using the generated filter. If the search does not return +exactly one entry, deny access. +. Attempt to bind to the LDAP server using the DN of the entry retrieved from +the search, and the user-provided password. +. If the bind is unsuccessful, deny access. +. If the bind is successful, build an identity using the configured attributes +as the identity, email address, display name, and preferred user name. + +The configured `url` is an RFC 2255 URL, which specifies the LDAP host and +search parameters to use. The syntax of the URL is: + +---- +ldap://host:port/basedn?attribute?scope?filter +---- + +For this URL: + +[cols="2a,8a",options="header"] +|=== +|URL Component | Description +.^|`ldap` | For regular LDAP, use the string `ldap`. For secure LDAP +(LDAPS), use `ldaps` instead. +.^|`host:port` | The name and port of the LDAP server. Defaults to +`localhost:389` for ldap and `localhost:636` for LDAPS. +.^|`basedn` | The DN of the branch of the directory where all searches should +start from. At the very least, this must be the top of your directory tree, but +it could also specify a subtree in the directory. +.^|`attribute` | The attribute to search for. Although RFC 2255 allows a +comma-separated list of attributes, only the first attribute will be used, no +matter how many are provided. If no attributes are provided, the default is to +use `uid`. It is recommended to choose an attribute that will be unique across +all entries in the subtree you will be using. +.^|`scope` | The scope of the search. Can be either `one` or `sub`. +If the scope is not provided, the default is to use a scope of `sub`. +.^|`filter` | A valid LDAP search filter. If not provided, defaults to +`(objectClass=*)` +|=== + +When doing searches, the attribute, filter, and provided user name are combined +to create a search filter that looks like: + +---- +(&()(=)) +---- + +For example, consider a URL of: + +---- +ldap://ldap.example.com/o=Acme?cn?sub?(enabled=true) +---- + +When a client attempts to connect using a user name of `bob`, the resulting +search filter will be `(&(enabled=true)(cn=bob))`. + +If the LDAP directory requires authentication to search, specify a `bindDN` and +`bindPassword` to use to perform the entry search. diff --git a/modules/identity-provider-about-request-header.adoc b/modules/identity-provider-about-request-header.adoc new file mode 100644 index 0000000000..ab09b97a2a --- /dev/null +++ b/modules/identity-provider-about-request-header.adoc @@ -0,0 +1,77 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-request-header-identity-provider.adoc + +[id='identity-provider-about-request-header-{context}'] += About request header authentication + +A request header identity provider identifies 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. + +You can also use the request header identity provider for advanced configurations +such as link:https://github.com/openshift/request-header-saml-service-provider[SAML authentication]. + +For users to authenticate using this identity provider, they must access +`\https:///oauth/authorize` (and subpaths) via an authenticating proxy. +To accomplish this, configure the OAuth server to redirect unauthenticated +requests for OAuth tokens to the proxy endpoint that proxies to `\https:///oauth/authorize`. + +To redirect unauthenticated requests from clients expecting browser-based login flows: + +1. Set the `login` parameter to `true`. +2. Set the `provider.loginURL` parameter to the authenticating proxy URL that +will authenticate interactive clients and then proxy the request to `\https:///oauth/authorize`. + +To redirect unauthenticated requests from clients expecting `WWW-Authenticate` challenges: + +1. Set the `challenge` parameter to `true`. +2. Set the `provider.challengeURL` parameter to the authenticating proxy URL that +will authenticate clients expecting `WWW-Authenticate` challenges and then proxy +the request to `\https:///oauth/authorize`. + +The `provider.challengeURL` and `provider.loginURL` parameters can include +the following tokens in the query portion of the URL: + +* `${url}` is replaced with the current URL, escaped to be safe in a query parameter. ++ +For example: `\https://www.example.com/sso-login?then=${url}` + +* `${query}` is replaced with the current query string, unescaped. ++ +For example: `\https://www.example.com/auth-proxy/oauth/authorize?${query}` + +[WARNING] +==== +If you expect unauthenticated requests to reach the OAuth server, a `clientCA` +parameter MUST be set for this identity provider, so that incoming requests +are checked for a valid client certificate before the request's headers are +checked for a user name. Otherwise, any direct request to the OAuth server can +impersonate any identity from this provider, merely by setting a request header. +==== + +[id='sspi-windows-{context}']] +== SSPI connection support on Microsoft Windows + +ifdef::openshift-enterprise[] + +[IMPORTANT] +==== +Using SSPI connection support on Microsoft Windows is a Technology Preview feature. +Technology Preview features are not supported with Red Hat production service +level agreements (SLAs), might not be functionally complete, and Red Hat does +not recommend to use them for production. These features provide early access to +upcoming product features, enabling customers to test functionality and provide +feedback during the development process. + +For more information on Red Hat Technology Preview features support scope, see +https://access.redhat.com/support/offerings/techpreview/. +==== + +endif::[] + +`oc` supports the Security Support Provider Interface (SSPI) to allow for SSO +flows on Microsft Windows. If you use the request header identity provider with a +GSSAPI-enabled proxy to connect an Active Directory server to {product-title}, +users can automatically authenticate to {product-title} by using the `oc` command +line interface from a domain-joined Microsoft Windows computer. diff --git a/modules/identity-provider-add.adoc b/modules/identity-provider-add.adoc new file mode 100644 index 0000000000..f9cf24deb2 --- /dev/null +++ b/modules/identity-provider-add.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-allow-all-identity-provider.adoc +// * authentication/identity_providers/configuring-deny-all-identity-provider.adoc +// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc +// * authentication/identity_providers/configuring-keystone-identity-provider.adoc +// * authentication/identity_providers/configuring-ldap-identity-provider.adoc +// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc +// * authentication/identity_providers/configuring-request-header-identity-provider.adoc +// * authentication/identity_providers/configuring-github-identity-provider.adoc +// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc +// * authentication/identity_providers/configuring-google-identity-provider.adoc +// * authentication/identity_providers/configuring-oidc-identity-provider.adoc + +[id='add-identity-provider-{context}'] += Adding an identity provider to your clusters + +After you install your cluster, add an identity provider to it so your +users can authenticate. + +.Prerequisites + +* Create an {product-title} cluster. +* Create the Custom Resource Definition (CRD) for your identity providers. + +.Procedure + +. Log in to the cluster as the `kube-admin` user: ++ +---- +$ command +---- + +. Start the authentication configuration wizard: + +. Review the default configuration information: + +. List the CRDs for your identity providers: + +. Restart the configuration server: + +. Log in to the cluster as a user from your identity provider: diff --git a/modules/identity-provider-allow-all-CRD.adoc b/modules/identity-provider-allow-all-CRD.adoc new file mode 100644 index 0000000000..d4c8a0d8ae --- /dev/null +++ b/modules/identity-provider-allow-all-CRD.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-allow-all-identity-provider.adoc + +[id='identity-provider-allow-all-CRD-{context}'] += Sample allow all CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for an +allow all identity provider. + +.Allow all CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_allow_provider <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: AllowAllPasswordIdentityProvider +---- +<1> This provider name is prefixed to provider 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 web +console) are redirected to a login page backed by this provider. +<4> Controls how mappings are established between this provider's identities and user objects. diff --git a/modules/identity-provider-basic-authentication-CRD.adoc b/modules/identity-provider-basic-authentication-CRD.adoc new file mode 100644 index 0000000000..85ad586d8a --- /dev/null +++ b/modules/identity-provider-basic-authentication-CRD.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc + +[id='identity-provider-basic-authentication-CRD-{context}'] += Sample basic authentication CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for an +basic authentication identity provider. + +.Basic authentication CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_remote_basic_auth_provider <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: BasicAuthPasswordIdentityProvider + url: https://www.example.com/remote-idp <5> + ca: /path/to/ca.file <6> + certFile: /path/to/client.crt <7> + keyFile: /path/to/client.key <8> +---- +<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 web +console) are redirected to a login page backed by this provider. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> URL accepting credentials in Basic authentication headers. +<6> Optional: Certificate bundle to use to validate server certificates for the +configured URL. +<7> Optional: Client certificate to present when making requests to the +configured URL. +<8> Key for the client certificate. Required if `certFile` is specified. diff --git a/modules/identity-provider-basic-authentication-troubleshooting.adoc b/modules/identity-provider-basic-authentication-troubleshooting.adoc new file mode 100644 index 0000000000..ec0ca6964a --- /dev/null +++ b/modules/identity-provider-basic-authentication-troubleshooting.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc + +[id='identity-provider-basic-authentication-troubleshooting{context}'] += Basic authentication troubleshooting + +The most common issue relates to network connectivity to the backend server. For +simple debugging, run `curl` commands on the master. To test for a successful +login, replace the `` and `` in the following example command +with valid credentials. To test an invalid login, replace them with false +credentials. + +---- +curl --cacert /path/to/ca.crt --cert /path/to/client.crt --key /path/to/client.key -u : -v https://www.example.com/remote-idp +---- + +*Successful responses* + +A `200` status with a `sub` (subject) key indicates success: + +---- +{"sub":"userid"} +---- +The subject must be unique to the authenticated user, and must not be able to +be modified. + +A successful response can optionally provide additional data, such as: + +* A display name using the `name` key: ++ +---- +{"sub":"userid", "name": "User Name", ...} +---- +* An email address using the `email` key: ++ +---- +{"sub":"userid", "email":"user@example.com", ...} +---- +* A preferred user name using the `preferred_username` key: ++ +---- +{"sub":"014fbff9a07c", "preferred_username":"bob", ...} +---- ++ +The `preferred_username` key 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 +{product-title} user for the authenticated identity. + +*Failed responses* + +- 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"}` diff --git a/modules/identity-provider-configuring-apache-request-header.adoc b/modules/identity-provider-configuring-apache-request-header.adoc new file mode 100644 index 0000000000..c029cb19be --- /dev/null +++ b/modules/identity-provider-configuring-apache-request-header.adoc @@ -0,0 +1,313 @@ +// Module included in the following assemblies: +// +// * orphaned + +[id='identity-provider-configuring-apache-request-header-{context}'] += Configuring Apache authentication using request header + +This example configures an authentication proxy on the same host as the master. +Having the proxy and master on the same host is merely a convenience and may not +be suitable for your environment. For example, if you were already +running a router +on the master, port 443 would not be available. + +It is also important to note that while this reference configuration uses +Apache's `mod_auth_gssapi`, it is by no means required and other proxies can +easily be used if the following requirements are met: + +1. Block the `X-Remote-User` header from client requests to prevent spoofing. +2. Enforce client certificate authentication in the `RequestHeaderIdentityProvider` configuration. +3. Require the `X-Csrf-Token` header be set for all authentication request using the challenge flow. +4. Only the `/oauth/authorize` endpoint and its subpaths should be proxied, +and redirects should not be rewritten to allow the backend server to send the client to the correct +location. +5. The URL that proxies to `\https:///oauth/authorize` must end with `/authorize` (with no trailing slash). For example: + * `\https://proxy.example.com/login-proxy/authorize?...` -> `\https:///oauth/authorize?...` +6. Subpaths of the URL that proxies to `\https:///oauth/authorize` must proxy to subpaths of `\https:///oauth/authorize`. For example: + * `\https://proxy.example.com/login-proxy/authorize/approve?...` -> `\https:///oauth/authorize/approve?...` + +. Obtain the `mod_auth_gssapi` module from the +link:https://access.redhat.com/solutions/392003[Optional channel]. +Install the following packages: ++ +[source,bash] +---- +# yum install -y httpd mod_ssl mod_session apr-util-openssl mod_auth_gssapi +---- + +. Generate a CA for validating requests that submit the trusted header. Use this CA +as the file name for `clientCA` in the identity provider configuration. ++ +---- +# oc adm ca create-signer-cert \ + --cert='/etc/origin/master/proxyca.crt' \ + --key='/etc/origin/master/proxyca.key' \ + --name='openshift-proxy-signer@1432232228' \ + --serial='/etc/origin/master/proxyca.serial.txt' +---- ++ +[NOTE] +==== +The `oc adm ca create-signer-cert` command generates a certificate that is valid +for five years. This can be altered with the `--expire-days` option, but for +security reasons, it is recommended to not make it greater than this +value. + +// Run `oc adm` commands only from the first master listed in the Ansible host inventory file, +// by default *_/etc/ansible/hosts_*. +==== + +. Generate a client certificate for the proxy. You can generate this certificate +by using any x509 certificate tooling, including the `oc adm` CLI: ++ +---- +# oc adm create-api-client-config \ + --certificate-authority='/etc/origin/master/proxyca.crt' \ + --client-dir='/etc/origin/master/proxy' \ + --signer-cert='/etc/origin/master/proxyca.crt' \ + --signer-key='/etc/origin/master/proxyca.key' \ + --signer-serial='/etc/origin/master/proxyca.serial.txt' \ + --user='system:proxy' <1> + +# pushd /etc/origin/master +# cp master.server.crt /etc/pki/tls/certs/localhost.crt <2> +# cp master.server.key /etc/pki/tls/private/localhost.key +# cp ca.crt /etc/pki/CA/certs/ca.crt +# cat proxy/system\:proxy.crt \ + proxy/system\:proxy.key > \ + /etc/pki/tls/certs/authproxy.pem +# popd +---- +<1> The user name can be anything, however it is useful to give it a descriptive +name as it will appear in logs. +<2> When running the authentication proxy on a different host name than the +master, it is important to generate a certificate that matches the host name +instead of using the default master certificate as shown above. The value for +`masterPublicURL` in the *_/etc/origin/master/master-config.yaml_* file +must be included in the `X509v3 Subject Alternative Name` in the certificate +that is specified for `SSLCertificateFile`. If a new certificate needs to be +created, the `oc adm ca create-server-cert` command can be used. ++ +[NOTE] +==== +The `oc adm create-api-client-config` command generates a certificate that is +valid for two years. This can be altered with the `--expire-days` option, but +for security reasons, it is recommended to not make it greater than +this value. +Run `oc adm` commands only from the first master listed in the Ansible host inventory file, +by default *_/etc/ansible/hosts_*. +==== + +[discrete] +===== Configuring Apache + +This proxy does not need to reside on the same +host as the master. It uses a client certificate to connect to the master, which +is configured to trust the `X-Remote-User` header. + +. Create the certificate for the Apache configuration. The certificate that you +specify as the `SSLProxyMachineCertificateFile` parameter value is the proxy's +client cert that is used to authenticate the proxy to the server. It must use +`TLS Web Client Authentication` as the extended key type. + + +. Create the Apache configuration. Use the following template to provide your +required settings and values: ++ +[IMPORTANT] +==== +Carefully review the template and customize its contents to fit your +environment. +==== ++ +---- +LoadModule request_module modules/mod_request.so +LoadModule auth_gssapi_module modules/mod_auth_gssapi.so +# Some Apache configurations might require these modules. +# LoadModule auth_form_module modules/mod_auth_form.so +# LoadModule session_module modules/mod_session.so + +# Nothing needs to be served over HTTP. This virtual host simply redirects to +# HTTPS. + + DocumentRoot /var/www/html + RewriteEngine On + RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R,L] + + + + # This needs to match the certificates you generated. See the CN and X509v3 + # Subject Alternative Name in the output of: + # openssl x509 -text -in /etc/pki/tls/certs/localhost.crt + ServerName www.example.com + + DocumentRoot /var/www/html + SSLEngine on + SSLCertificateFile /etc/pki/tls/certs/localhost.crt + SSLCertificateKeyFile /etc/pki/tls/private/localhost.key + SSLCACertificateFile /etc/pki/CA/certs/ca.crt + + SSLProxyEngine on + SSLProxyCACertificateFile /etc/pki/CA/certs/ca.crt + # It's critical to enforce client certificates on the Master. Otherwise + # requests could spoof the X-Remote-User header by accessing the Master's + # /oauth/authorize endpoint directly. + SSLProxyMachineCertificateFile /etc/pki/tls/certs/authproxy.pem + + # Send all requests to the console + RewriteEngine On + RewriteRule ^/console(.*)$ https://%{HTTP_HOST}:8443/console$1 [R,L] + + # In order to using the challenging-proxy an X-Csrf-Token must be present. + RewriteCond %{REQUEST_URI} ^/challenging-proxy + RewriteCond %{HTTP:X-Csrf-Token} ^$ [NC] + RewriteRule ^.* - [F,L] + + + # Insert your backend server name/ip here. + ProxyPass https://[MASTER]:8443/oauth/authorize + AuthName "SSO Login" + # For Kerberos + AuthType GSSAPI + Require valid-user + RequestHeader set X-Remote-User %{REMOTE_USER}s + + GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab + # Enable the following if you want to allow users to fallback + # to password based authntication when they do not have a client + # configured to perform kerberos authentication + GssapiBasicAuth On + + # For ldap: + # AuthBasicProvider ldap + # AuthLDAPURL "ldap://ldap.example.com:389/ou=People,dc=my-domain,dc=com?uid?sub?(objectClass=*)" + + # It's possible to remove the mod_auth_gssapi usage and replace it with + # something like mod_auth_mellon, which only supports the login flow. + + + + # Insert your backend server name/ip here. + ProxyPass https://[MASTER]:8443/oauth/authorize + + AuthName "SSO Login" + AuthType GSSAPI + Require valid-user + RequestHeader set X-Remote-User %{REMOTE_USER}s env=REMOTE_USER + + GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab + # Enable the following if you want to allow users to fallback + # to password based authntication when they do not have a client + # configured to perform kerberos authentication + GssapiBasicAuth On + + ErrorDocument 401 /login.html + + + + +RequestHeader unset X-Remote-User +---- + +[discrete] +===== Configuring the master + +[[requestheader-master-ca-config]] +The `identityProviders` stanza in the +*_/etc/origin/master/master-config.yaml_* file must be updated as well: + +---- + identityProviders: + - name: requestheader + challenge: true + login: true + provider: + apiVersion: v1 + kind: RequestHeaderIdentityProvider + challengeURL: "https://[MASTER]/challenging-proxy/oauth/authorize?${query}" + loginURL: "https://[MASTER]/login-proxy/oauth/authorize?${query}" + clientCA: /etc/origin/master/proxyca.crt + headers: + - X-Remote-User +---- + +[discrete] +===== Restarting services + +Finally, restart the following services: + +---- +# systemctl restart httpd +# master-restart api +# master-restart controllers +---- + +[discrete] +===== Verifying the configuration + +. Test by bypassing the proxy. You should be able to request a token if you +supply the correct client certificate and header: ++ +---- +# curl -L -k -H "X-Remote-User: joe" \ + --cert /etc/pki/tls/certs/authproxy.pem \ + https://[MASTER]:8443/oauth/token/request +---- + +. If you do not supply the client certificate, the request should be denied: ++ +---- +# curl -L -k -H "X-Remote-User: joe" \ + https://[MASTER]:8443/oauth/token/request +---- + +. This should show a redirect to the configured `challengeURL` (with +additional query parameters): ++ +---- +# curl -k -v -H 'X-Csrf-Token: 1' \ + '/oauth/authorize?client_id=openshift-challenging-client&response_type=token' +---- + +. This should show a 401 response with a `WWW-Authenticate` basic challenge, a +negotiate challenge, or both challenges: ++ +---- +# curl -k -v -H 'X-Csrf-Token: 1' \ + '' +---- + +. Test logging into the `oc` command line with and without using a Kerberos ticket: +.. If you generated a Kerberos ticket by using `kinit`, destroy it: ++ +---- +# kdestroy -c cache_name <1> +---- +<1> Provide the name of your Kerberos cache. +.. Log in to the `oc` command line by using your Kerberos credentials: ++ +---- +# oc login +---- ++ +Enter your Kerberos user name and password at the prompt. +.. Log out of the `oc` command line: ++ +---- +# oc logout +---- +.. Use your Kerberos credentials to get a ticket: ++ +---- +# kinit +---- ++ +Enter your Kerberos user name and password at the prompt. +.. Confirm that you can log in to the `oc` command line: ++ +---- +# oc login +---- ++ +If your configuration is correct, you are logged in without entering separate +credentials. diff --git a/modules/identity-provider-configuring-basic-authentication.adoc b/modules/identity-provider-configuring-basic-authentication.adoc new file mode 100644 index 0000000000..dc1e53b162 --- /dev/null +++ b/modules/identity-provider-configuring-basic-authentication.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc + +[id='identity-provider-configuring-basic-authentication-{context}'] += Configuring basic authentication + +You might need to take more steps to prepare your cluster for basic authentication. + +. If you have: ++ +- Already completed the installation of Openshift, then copy the +*_/etc/origin/master/master-config.yaml_* file into a new directory; for example: ++ +---- +$ mkdir basicauthconfig; cp master-config.yaml basicauthconfig +---- ++ +- Not yet installed {product-title}, then start the {product-title} API server, +specifying the hostname of the (future) {product-title} master and a directory +to store the configuration file created by the start command: ++ +---- +$ openshift start master --public-master= --write-config= +---- ++ +For example: ++ +---- +$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=basicauthconfig +---- ++ +[NOTE] +==== +If you are installing with Ansible, then you must add the +`identityProvider` configuration to the Ansible playbook. +If you use the following steps to modify your configuration manually after installing with Ansible, then you will lose any modifications whenever you re-run the install tool or upgrade. +==== ++ +. Edit the new *_master-config.yaml_* file's `identityProviders` stanza, and +copy the +example `BasicAuthPasswordIdentityProvider` configuration and paste it to +replace the existing stanza: + +. Make the following modifications to the `identityProviders` stanza: +.. Set the provider `name` to something unique and relevant to your +deployment. This name is prefixed to the returned user ID to form an identity +name. +.. If required, set `mappingMethod` to control how mappings are established between the +provider's identities and user objects. +.. Specify the HTTPS `url` to use to connect to a server that accepts credentials in Basic authentication headers. +.. Optionally, set the `ca` to the certificate bundle to use in order to validate server certificates for the configured URL, or leave it empty to use the system-trusted roots. +.. Optionally, remove or set the `certFile` to the client certificate to present when making requests to the configured URL. +.. If `certFile` is specified, then you must set the `keyFile` to the key for the client certificate. +. Save your changes and close the file. +. Start the {product-title} API server, specifying the configuration file you just +modified: ++ +---- +$ openshift start master --config=/master-config.yaml +---- + +Once configured, any user logging in to the {product-title} web console will be +prompted to log in using their Basic authentication credentials. diff --git a/modules/identity-provider-configuring-github.adoc b/modules/identity-provider-configuring-github.adoc new file mode 100644 index 0000000000..807b818e92 --- /dev/null +++ b/modules/identity-provider-configuring-github.adoc @@ -0,0 +1,84 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-github-identity-provider.adoc + +[id='identity-provider-configuring-github-{context}'] += Configuring GitHub + +You might need to take more steps to register GitHub as your identity provider. + +.Prerequisites + +* Register an application on GitHub or GitHub Enterprise to obtain a +Client ID and Client Secret. + +.Procedure + +. If you have: +- Already installed {product-title}, then copy the +*_/etc/origin/master/master-config.yaml_* file into a new directory, for example: ++ +---- +$ cd /etc/origin/master +$ mkdir githubconfig; cp master-config.yaml githubconfig +---- +- Not yet installed {product-title}, then start the {product-title} API server, +specifying the hostname of the (future) {product-title} master and a directory +to store the configuration file created by the start command: ++ +---- +$ openshift start master --public-master= --write-config= +---- ++ +For example: ++ +---- +$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=githubconfig +---- ++ +[NOTE] +==== +If you are installing with Ansible, then you must add the +`identityProvider` configuration to the Ansible playbook. +If you use the following steps to modify your configuration manually after installing with Ansible, then you will lose any modifications whenever you re-run the install tool or upgrade. +==== ++ +[NOTE] +==== +Using `openshift start master` on its own would auto-detect host names, but +GitHub must be able to redirect to the exact host name that you specified when +registering the application. For this reason, you cannot auto-detect the ID +because it might redirect to the wrong address. Instead, you must specify the +hostname that web browsers use to interact with your {product-title} cluster. +==== +. Edit the new *_master-config.yaml_* file's `identityProviders` stanza, and copy the example `GitHubIdentityProvider` configuration +and paste it to replace the existing stanza: + +. Make the following modifications to the `identityProviders` stanza: +.. Change the provider `name` to match the callback URL you configured on +GitHub. ++ +For example, if you defined the callback URL as +`https://myapiserver.com:8443/oauth2callback/github/` then the `name` must be +`github`. +.. Change `clientID` to the Client ID from GitHub that you registered previously. +.. Change `clientSecret` to the Client Secret from GitHub that you +registered previously. +.. Change `organizations` or `teams` to include a list of one or more GitHub +organizations or teams to which a user must have membership in order to authenticate. If +specified, only GitHub users that are members of at least one of the listed +organizations or teams will be allowed to log in. If this is not specified, then any +person with a valid GitHub account can log in. +. Save your changes and close the file. +. Start the {product-title} API server, specifying the configuration file you just +modified: ++ +---- +$ openshift start master --config=/master-config.yaml +---- + +Once configured, any user logging in to the {product-title} web console will be +prompted to log in using their GitHub credentials. On their first login, the +user must click *authorize application* to permit GitHub to use their user name, +password, and organization membership with {product-title}. The user is then +redirected back to the web console. diff --git a/modules/identity-provider-configuring-keystone.adoc b/modules/identity-provider-configuring-keystone.adoc new file mode 100644 index 0000000000..5cb24bb6ea --- /dev/null +++ b/modules/identity-provider-configuring-keystone.adoc @@ -0,0 +1,79 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-keystone-identity-provider.adoc + +[id='identity-provider-configuring-keystone-{context}'] += Configuring your cluster for Keystone + +You might need to take more steps to prepare your cluster for Keystone. + +.Procedure + +. If you have: +- Already completed the installation of Openshift, then copy the +*_/etc/origin/master/master-config.yaml_* file into a new directory; for example: ++ +---- +$ cd /etc/origin/master +$ mkdir keystoneconfig; cp master-config.yaml keystoneconfig +---- +- Not yet installed {product-title}, then start the {product-title} API server, +specifying the hostname of the (future) {product-title} master and a directory +to store the configuration file created by the start command: ++ +---- +$ openshift start master --public-master= --write-config= +---- ++ +For example: ++ +---- +$ openshift start master --public-master=https://myapiserver.com:8443 --write-config=keystoneconfig +---- ++ +[NOTE] +==== +If you are installing with Ansible, then you must add the +`identityProvider` configuration to the Ansible playbook. +If you use the following steps to modify your configuration manually after installing with Ansible, then you will lose any modifications whenever you re-run the install tool or upgrade. +==== ++ +. Edit the new *_keystoneconfig/master-config.yaml_* file's `identityProviders` stanza, and copy the example `KeystonePasswordIdentityProvider` configuration +and paste it to replace the existing stanza: ++ + +. Make the following modifications to the `identityProviders` stanza: +.. Change the provider `name` ("my_keystone_provider") to match your Keystone server. +This name is prefixed to provider user names to form an identity name. +.. If required, +change `mappingMethod` to control how mappings are established between the +provider's identities and user objects. +.. Change the `domainName` to the domain name of your OpenStack Keystone server. In Keystone, user names are domain-specific. Only a single domain is supported. +.. Specify the `url` to use to connect to your OpenStack Keystone server. +.. Optionally, to authenticate users by Keystone ID instead of Keystone user +name, set `useKeystoneIdentity` to `true`. +.. Optionally, change the `ca` to the certificate bundle to use in order to validate server certificates for the configured URL. +.. Optionally, change the `certFile` to the client certificate to present when making requests to the configured URL. +.. If `certFile` is specified, then you must change the `keyFile` to the key for the client certificate. +. Save your changes and close the file. +. Start the {product-title} API server, specifying the configuration file you just +modified: ++ +---- +$ openshift start master --config=/master-config.yaml +---- + +Once configured, any user logging in to the {product-title} web console will be +prompted to log in using their Keystone credentials. + + +Once one or more users have logged in, you can run `oc get users` to view a +list of users and verify that users were created successfully: + +.Output of `oc get users` command +---- +$ oc get users +NAME UID FULL NAME IDENTITIES +bobsmith a0c1d95c-1cb5-11e6-a04a-002186a28631 Bob Smith keystone:bobsmith <1> +---- +<1> Identities in {product-title} are comprised of the identity provider name prefixed to the Keystone user name. diff --git a/modules/identity-provider-create-CRD.adoc b/modules/identity-provider-create-CRD.adoc new file mode 100644 index 0000000000..5fe8fbcf84 --- /dev/null +++ b/modules/identity-provider-create-CRD.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-allow-all-identity-provider.adoc +// * authentication/identity_providers/configuring-deny-all-identity-provider.adoc +// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc +// * authentication/identity_providers/configuring-keystone-identity-provider.adoc +// * authentication/identity_providers/configuring-ldap-identity-provider.adoc +// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc +// * authentication/identity_providers/configuring-request-header-identity-provider.adoc +// * authentication/identity_providers/configuring-github-identity-provider.adoc +// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc +// * authentication/identity_providers/configuring-google-identity-provider.adoc +// * authentication/identity_providers/configuring-oidc-identity-provider.adoc + +[id='identity-provider-create-CRD-{context}'] += Creating the CRD that describes an identity provider + +Before you can add an identity provider to your cluster, create a Custom +Resource Definition (CRD) that describes it. + +.Prerequisites + +* Create an {product-title} cluster. + +.Procedure + +. Log in to the cluster as: ++ +[source,bash] +---- +$ command +---- + +. Create the CRD for your identity provider: ++ +[source,bash] +---- +$ command +---- ++ +Provide the parameters that are required for your identity provider type. diff --git a/modules/identity-provider-creating-htpasswd-file.adoc b/modules/identity-provider-creating-htpasswd-file.adoc new file mode 100644 index 0000000000..ef66ff6473 --- /dev/null +++ b/modules/identity-provider-creating-htpasswd-file.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc + +[id='identity-provider-creating-htpasswd-file-{context}'] += Creating an HTPasswd file + +To use the HTPasswd identity provider, you must generate a flat file that +contains the user names and passwords for your cluster by using +link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. + +.Procedure + +. Install the `htpasswd` utility by installing the `httpd-tools` package: ++ +[source,bash] +---- +# yum install httpd-tools +---- + +. Create or update your with a user name and hashed password: ++ +[source,bash] +---- +$ htpasswd -c -b +---- ++ +The command generates a hashed version of the password. ++ +For example: ++ +[source,bash] +---- +$ htpasswd -c -b users.htpasswd user1 MyPassword! + +Adding password for user user1 +---- + +. Continue to add or update credentials to the file: ++ +[source,bash] +---- +$ htpasswd -b +---- diff --git a/modules/identity-provider-default-CRD.adoc b/modules/identity-provider-default-CRD.adoc new file mode 100644 index 0000000000..0d51e55d70 --- /dev/null +++ b/modules/identity-provider-default-CRD.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * authentication/understanding-identity-provider.adoc + +[id='identity-provider-default-CRD-{context}'] += Sample identity provider CRD + +The following Custom Resource Definition (CRD) shows the parameters and default +values for that you use to configure an identity provider. + +.Sample identity provider CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_allow_provider <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: AllowAllPasswordIdentityProvider +---- +<1> This provider name is prefixed to provider 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 web +console) are redirected to a login page backed by this provider. +<4> Controls how mappings are established between this provider's identities and user objects. diff --git a/modules/identity-provider-deny-all-CRD.adoc b/modules/identity-provider-deny-all-CRD.adoc new file mode 100644 index 0000000000..a7142670a0 --- /dev/null +++ b/modules/identity-provider-deny-all-CRD.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-deny-all-identity-provider.adoc + +[id='identity-provider-deny-all-CRD-{context}'] += Sample deny all CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for a +deny all identity provider. + +.Deny all CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_deny_provider <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: DenyAllPasswordIdentityProvider +---- +<1> This provider name is prefixed to provider 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 web +console) are redirected to a login page backed by this provider. +<4> Controls how mappings are established between this provider's identities and user objects. diff --git a/modules/identity-provider-github-CRD.adoc b/modules/identity-provider-github-CRD.adoc new file mode 100644 index 0000000000..50f432b9ff --- /dev/null +++ b/modules/identity-provider-github-CRD.adoc @@ -0,0 +1,68 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-github-identity-provider.adoc + +[id='identity-provider-github-CRD-{context}'] += Sample GitHub CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for a +GitHub identity provider. + +.GitHub CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: github <1> + challenge: false <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: GitHubIdentityProvider + ca: ... <5> + clientID: ... <6> + clientSecret: ... <7> + hostname: ... <8> + organizations: <9> + - myorganization1 + - myorganization2 + teams: <10> + - myorganization1/team-a + - myorganization2/team-b +---- +<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) are redirected to GitHub to log in. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> For GitHub Enterprise, the CA is the optional trusted certificate authority +bundle to use when making requests to the server. Omit this parameter to use the +default system root certificates. For GitHub, omit this parameter. +<6> 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/`. +<7> The client secret issued by GitHub. This value may also be provided in an +environment variable, external file, or encrypted file. +// Might need another link? install_config/master_node_configuration.adoc#master-node-configuration-passwords-and-other-data +<8> For GitHub Enterprise, you must provide the host name of your instance, such as +`example.com`. This value must match the GitHub Enterprise `hostname` value in +in the *_/setup/settings_* file and cannot include a port number. For GitHub, +omit this parameter. +<9> Optional list of organizations. If specified, only GitHub users that are members of +at least one of the listed organizations will be allowed to log in. If the GitHub OAuth +application configured in `clientID` is not owned by the organization, an organization +owner must grant third-party access in order to use this option. This can be done during +the first GitHub login by the organization's administrator, or from the GitHub organization settings. +Cannot be used in combination with the `teams` field. +<10> Optional list of teams. If specified, only GitHub users that are members of +at least one of the listed teams will be allowed to log in. If the GitHub OAuth +application configured in `clientID` is not owned by the team's organization, an organization +owner must grant third-party access in order to use this option. This can be done during +the first GitHub login by the organization's administrator, or from the GitHub organization settings. +Cannot be used in combination with the `organizations` field. diff --git a/modules/identity-provider-gitlab-CRD.adoc b/modules/identity-provider-gitlab-CRD.adoc new file mode 100644 index 0000000000..6f8060f04d --- /dev/null +++ b/modules/identity-provider-gitlab-CRD.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc + +[id='identity-provider-gitlab-CRD-{context}'] += Sample GitLab CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for a +GitLab identity provider. + +.GitLab CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: gitlab <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: GitLabIdentityProvider + legacy: <5> + url: ... <6> + clientID: ... <7> + clientSecret: ... <8> + ca: ... <9> +---- +<1> This provider name is prefixed to the GitLab numeric user ID to form an +identity name. It is also used to build the callback URL. +<2> When `true`, unauthenticated token requests from non-web clients (like +the CLI) are sent a `WWW-Authenticate` challenge header for this provider. +This uses the link:http://doc.gitlab.com/ce/api/oauth2.html#resource-owner-password-credentials[Resource Owner Password Credentials] +grant flow to obtain an access token from GitLab. +<3> When `true`, unauthenticated token requests from web clients (like the web +console) are redirected to GitLab to log in. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> Determines whether to use OAuth or OIDC as the authentication provider. Set +to `true` to use OAuth and `false` to use OIDC. You must use GitLab.com or +GitLab version 11.1 or later to use OIDC. If you do not provide a value, OAuth +is used to connect to your GitLab instance, and OIDC is used to connect to +GitLab.com. +<6> The host URL of a GitLab provider. This could either be `\https://gitlab.com/` +or any other self hosted instance of GitLab. +<7> The client ID of a +link:https://docs.gitlab.com/ce/api/oauth2.html[registered GitLab OAuth application]. +The application must be configured with a callback URL of +`/oauth2callback/`. +<8> The client secret issued by GitLab. This value may also be provided in an +environment variable, external file, or encrypted file. +<9> CA is an optional trusted certificate authority bundle to use when making +requests to the GitLab instance. If empty, the default system roots are used. diff --git a/modules/identity-provider-google-CRD.adoc b/modules/identity-provider-google-CRD.adoc new file mode 100644 index 0000000000..a2c0ac6ee9 --- /dev/null +++ b/modules/identity-provider-google-CRD.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-google-identity-provider.adoc + +[id='identity-provider-google-CRD-{context}'] += Sample Google CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for a +Google identity provider. + +.Google CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: google <1> + challenge: false <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: GoogleIdentityProvider + clientID: ... <5> + clientSecret: ... <6> + hostedDomain: "" <7> +---- +<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) are redirected to Google to log in. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> 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/`. +<6> The client secret issued by Google. This value may also be provided in an +environment variable, external file, or encrypted file. +<7> 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. diff --git a/modules/identity-provider-htpasswd-CRD.adoc b/modules/identity-provider-htpasswd-CRD.adoc new file mode 100644 index 0000000000..a14c16203f --- /dev/null +++ b/modules/identity-provider-htpasswd-CRD.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc + +[id='identity-provider-htpasswd-CRD-{context}'] += Sample HTPasswd CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for an +HTPasswd identity provider. + +.HTPasswd CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_htpasswd_provider <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: HTPasswdPasswordIdentityProvider + file: /path/to/users.htpasswd <5> +---- +<1> This provider name is prefixed to provider 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 web +console) are redirected to a login page backed by this provider. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> File generated using +link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. diff --git a/modules/identity-provider-keystone-CRD.adoc b/modules/identity-provider-keystone-CRD.adoc new file mode 100644 index 0000000000..ff0858de43 --- /dev/null +++ b/modules/identity-provider-keystone-CRD.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-keystone-identity-provider.adoc + +[id='identity-provider-keystone-CRD-{context}'] += Sample Keystone CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for a +Keystone identity provider. + +.Keystone CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_keystone_provider <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: KeystonePasswordIdentityProvider + domainName: default <5> + url: http://keystone.example.com:5000 <6> + ca: ca.pem <7> + certFile: keystone.pem <8> + keyFile: keystonekey.pem <9> + useKeystoneIdentity: false <10> +---- +<1> This provider name is prefixed to provider 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 web +console) are redirected to a login page backed by this provider. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is supported. +<6> The URL to use to connect to the Keystone server (required). +<7> Optional: Certificate bundle to use to validate server certificates for the configured URL. +<8> Optional: Client certificate to present when making requests to the configured URL. +<9> Key for the client certificate. Required if `certFile` is specified. +<10> When `true`, indicates that user is authenticated by Keystone ID, not by +Keystone user name. Set to `false` to authenticate by user name. diff --git a/modules/identity-provider-ldap-CRD.adoc b/modules/identity-provider-ldap-CRD.adoc new file mode 100644 index 0000000000..492b34c53e --- /dev/null +++ b/modules/identity-provider-ldap-CRD.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-ldap-identity-provider.adoc + +[id='identity-provider-ldap-CRD-{context}'] += Sample LDAP CRD + +The following Custom Resource Definition (CRD) shows the parameters and acceptable values for an +LDAP identity provider. + +.LDAP CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: "my_ldap_provider" <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: LDAPPasswordIdentityProvider + attributes: + id: <5> + - dn + email: <6> + - mail + name: <7> + - cn + preferredUsername: <8> + - uid + bindDN: "" <9> + bindPassword: "" <10> + ca: my-ldap-ca-bundle.crt <11> + insecure: false <12> + url: "ldap://ldap.example.com/ou=users,dc=acme,dc=com?uid" <13> +---- +<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 web +console) are redirected to a login page backed by this provider. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> List of attributes to use as the identity. First non-empty attribute is +used. At least one attribute is required. If none of the listed attribute have a +value, authentication fails. +<6> List of attributes to use as the email address. First non-empty attribute is +used. +<7> List of attributes to use as the display name. First non-empty attribute is +used. +<8> List of attributes to use as the preferred user name when provisioning a +user for this identity. First non-empty attribute is used. +<9> Optional DN to use to bind during the search phase. +<10> Optional password to use to bind during the search phase. This value may also be +provided in an environment variable, external file, or encrypted file. +// Check to see if this needs another include. It was in install_config/master_node_configuration.adoc#master-node-configuration-passwords-and-other-data +<11> Certificate bundle to use to validate server certificates for the +configured URL. If empty, system trusted roots are used. Only applies if +`insecure: false`. +<12> When `true`, no TLS connection is made to the server. When `false`, +`ldaps://` URLs connect using TLS, and `ldap://` URLs are upgraded to TLS. +<13> An RFC 2255 URL which specifies the LDAP host and search parameters to use. + +[NOTE] +==== +To whitelist users for an LDAP integration, use the `lookup` mapping method. +Before a login from LDAP would be allowed, a cluster administrator must create +an identity and user object for each LDAP user. +==== diff --git a/modules/identity-provider-oidc-CRD.adoc b/modules/identity-provider-oidc-CRD.adoc new file mode 100644 index 0000000000..004cd39a26 --- /dev/null +++ b/modules/identity-provider-oidc-CRD.adoc @@ -0,0 +1,117 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-oidc-identity-provider.adoc + +[id='identity-provider-oidc-CRD-{context}'] += Sample OpenID Connect CRDs + +The following Custom Resource Definition (CRD)s shows the parameters and acceptable values for an +OpenID Connect identity provider. + +If you need to specify a custom certificate bundle, extra scopes, extra authorization request +parameters, or a `userInfo` URL, use the full OpenID Connect CRD. + +.Standard OpenID Connect CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_openid_connect <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: OpenIDIdentityProvider + clientID: ... <5> + clientSecret: ... <6> + claims: + id: <7> + - sub + preferredUsername: + - preferred_username + name: + - name + email: + - email + urls: + authorize: https://myidp.example.com/oauth2/authorize <8> + token: https://myidp.example.com/oauth2/token <9> +---- +<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> When `true`, unauthenticated token requests from non-web clients (like +the CLI) are sent a `WWW-Authenticate` challenge header for this provider. +This requires the OpenID provider to support the +link:https://tools.ietf.org/html/rfc6749#section-1.3.3[Resource Owner Password Credentials] grant flow. +<3> When `true`, unauthenticated token requests from web clients (like the web +console) are redirected to the authorize URL to log in. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> The client ID of a client registered with the OpenID provider. The client +must be allowed to redirect to `/oauth2callback/`. +<6> The client secret. This value may also be provided in an +environment variable, external file, or encrypted file. +<7> 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. For example, this uses the value of the `sub` claim in the returned `id_token` as the user's identity. +<8> link:http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] +described in the OpenID spec. Must use `https`. +<9> link:http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] +described in the OpenID spec. Must use `https`. + +.Full OpenID Connect CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_openid_connect + challenge: false + login: true + mappingMethod: claim + 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 fails. +<5> List of claims to use as the preferred user name 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`. diff --git a/modules/identity-provider-overview.adoc b/modules/identity-provider-overview.adoc new file mode 100644 index 0000000000..6e75778d68 --- /dev/null +++ b/modules/identity-provider-overview.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * authentication/configuring-identity-provider.adoc +// * authentication/identity_providers/configuring-allow-all-identity-provider.adoc +// * authentication/identity_providers/configuring-deny-all-identity-provider.adoc +// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc +// * authentication/identity_providers/configuring-keystone-identity-provider.adoc +// * authentication/identity_providers/configuring-ldap-identity-provider.adoc +// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc +// * authentication/identity_providers/configuring-request-header-identity-provider.adoc +// * authentication/identity_providers/configuring-github-identity-provider.adoc +// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc +// * authentication/identity_providers/configuring-google-identity-provider.adoc +// * authentication/identity_providers/configuring-oidc-identity-provider.adoc + +[id='identity-provider-overview-{context}'] += About identity providers in {product-title} + +By default, only a `kube-admin` user exists on +your cluster. To specify an identity provider, you must create a Custom Resource +Definition (CRD) that describes that identity provider and add it to the cluster. + +[NOTE] +==== +{product-title} user names containing `/`, `:`, and `%` are not supported. +==== diff --git a/modules/identity-provider-parameters.adoc b/modules/identity-provider-parameters.adoc new file mode 100644 index 0000000000..88754ee7c1 --- /dev/null +++ b/modules/identity-provider-parameters.adoc @@ -0,0 +1,58 @@ +// Module included in the following assemblies: +// +// * authentication/understanding-identity-provider.adoc + +[id='identity-provider-parameters-{context}'] += Identity provider parameters + +Four parameters are common to all identity providers: + +[cols="2a,8a",options="header"] +|=== +|Parameter | Description +|`name` | The provider name is prefixed to provider user names to form an +identity name. +|`challenge` | When `true`, unauthenticated token requests from non-web +clients (like the CLI) are sent a `WWW-Authenticate` challenge header. Not +supported by all identity providers. + +To prevent cross-site request forgery (CSRF) attacks against browser clients +Basic authentication challenges are only 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. + +|`login` | When `true`, unauthenticated token requests from web clients +(like the web console) are redirected to a login page backed by this provider. +Not supported by all identity providers. + +If you want users to be sent to a branded page before being redirected to +the identity provider's login, then set `oauthConfig -> alwaysShowProviderSelection: true` +in the master configuration file. + +|`mappingMethod` | Defines how new identities are mapped to users when they log in. +Enter one of the following values: + +claim:: The default value. Provisions a user with the identity's preferred +user name. Fails if a user with that user name is already mapped to another +identity. +lookup:: Looks up an existing identity, user identity mapping, and user, +but does not automatically provision users or identities. This allows cluster +administrators to set up identities and users manually, or using an external +process. Using this method requires you to manually provision users. +generate:: Provisions a user with the identity's preferred user name. If a +user with the preferred user name is already mapped to an existing identity, a +unique user name is generated. For example, `myuser2`. This method should not be +used in combination with external processes that require exact matches between +{product-title} user names and identity provider user names, such as LDAP group +sync. +add:: Provisions a user with the identity's preferred user name. If a user +with that user name already exists, the identity is mapped to the existing user, +adding to any existing identity mappings for the user. Required when multiple +identity providers are configured that identify the same set of users and map to +the same user names. +|=== + +[NOTE] +When adding or changing identity providers, you can map identities from the new +provider to existing users by setting the `mappingMethod` parameter to +`add`. diff --git a/modules/identity-provider-provisioning-user-lookup-mapping.adoc b/modules/identity-provider-provisioning-user-lookup-mapping.adoc new file mode 100644 index 0000000000..b81028637f --- /dev/null +++ b/modules/identity-provider-provisioning-user-lookup-mapping.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * orphaned + +[id='identity-provider-provisioning-user-lookup-mapping-{context}'] += Manually provisioning a user when using the lookup mapping method + +When using the `lookup` mapping method, user provisioning is done by an external system, via the API. +Typically, identities are automatically mapped to users during login. The 'lookup' mapping method automatically +disables this automatic mapping, which requires you to provision users manually. + + +.Procedure + +If you are using the `lookup` mapping method, use the following steps for each user after configuring +the identity provider: + +. Create an {product-title} User, if not created already: ++ +---- +$ oc create user +---- ++ +For example, the following command creates a {product-title} User `bob`: ++ +---- +$ oc create user bob +---- + +. Create an {product-title} Identity, if not created already. Use the name of the identity provider and +the name that uniquely represents this identity in the scope of the identity provider: ++ +---- +$ oc create identity : +---- ++ +The `` is the name of the identity provider in the master configuration, +as shown in the appropriate identity provider section below. ++ +For example, the following commands creates an Identity with identity provider `ldap_provider` and the identity provider user name `bob_s`. ++ +---- +$ oc create identity ldap_provider:bob_s +---- + +. Create a user/identity mapping for the created user and identity: ++ +---- +$ oc create useridentitymapping : +---- ++ +For example, the following command maps the identity to the user: ++ +---- +$ oc create useridentitymapping ldap_provider:bob_s bob +---- diff --git a/modules/identity-provider-registering-github.adoc b/modules/identity-provider-registering-github.adoc new file mode 100644 index 0000000000..a7bea980b1 --- /dev/null +++ b/modules/identity-provider-registering-github.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-github-identity-provider.adoc + +[id='identity-provider-registering-github-{context}'] += Registering a GitHub application + +To use GitHub or GitHub Enterprise as an identity provider, you must register +an application to use. + +.Procedure + +. Register an application on GitHub: +** For GitHub, click https://github.com/settings/profile[Settings] -> +https://github.com/settings/developers[Developer settings] -> +https://github.com/settings/applications/new[Register a new OAuth application]. +** For GitHub Enterprise, go to your GitHub Enterprise home page and then click +*Settings -> Developer settings -> Register a new application*. +. Enter an application name, for example `My OpenShift Install`. +. Enter a homepage URL, such as `https://myapiserver.com:8443`. +. Optionally, enter an application description. +. Enter the authorization callback URL, where the end of the URL contains the +identity provider `name`: ++ +---- +/oauth2callback/ +---- ++ +For example: ++ +---- +https://myapiserver.com:8443/oauth2callback/github/ +---- +. Click *Register application*. GitHub provides a Client ID and a Client Secret. +You need these values to complete the identity provider configuration. diff --git a/modules/identity-provider-request-header-CRD.adoc b/modules/identity-provider-request-header-CRD.adoc new file mode 100644 index 0000000000..0676ef3dc6 --- /dev/null +++ b/modules/identity-provider-request-header-CRD.adoc @@ -0,0 +1,74 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-request-header-identity-provider.adoc + +[id='identity-provider-request-header-CRD-{context}'] += Sample request header CRD + +The following Custom Resource Definition (CRD) shows the parameters and +acceptable values for a request header identity provider. + +.Request header CRD + +[source,yaml] +---- +oauthConfig: + ... + identityProviders: + - name: my_request_header_provider <1> + challenge: true <2> + login: true <3> + mappingMethod: claim <4> + provider: + apiVersion: v1 + kind: RequestHeaderIdentityProvider + challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" <5> + loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" <6> + clientCA: /path/to/client-ca.file <7> + clientCommonNames: <8> + - my-auth-proxy + headers: <9> + - X-Remote-User + - SSO-User + emailHeaders: <10> + - X-Remote-User-Email + nameHeaders: <11> + - X-Remote-User-Display-Name + preferredUsernameHeaders: <12> + - X-Remote-User-Login +---- +<1> This provider name is prefixed to the user name in the request header to +form an identity name. +<2> `RequestHeaderIdentityProvider` can only respond to clients that request +`WWW-Authenticate` challenges by redirecting to a configured `challengeURL`. The +configured URL should respond with a `WWW-Authenticate` challenge. +<3> `RequestHeaderIdentityProvider` can only respond to clients requesting a +login flow by redirecting to a configured `loginURL`. The configured URL should +respond with a login flow. +<4> Controls how mappings are established between this provider's identities and user objects. +<5> Optional: URL to redirect unauthenticated `/oauth/authorize` requests to, +that will authenticate browser-based clients and then proxy their request to `\https:///oauth/authorize`. +The URL that proxies to `\https:///oauth/authorize` must end with `/authorize` (with no trailing slash), +and also proxy subpaths, in order for OAuth approval flows to work properly. +`${url}` is replaced with the current URL, escaped to be safe in a query parameter. +`${query}` is replaced with the current query string. +<6> Optional: URL to redirect unauthenticated `/oauth/authorize` requests to, +that will authenticate clients which expect `WWW-Authenticate` challenges, and then proxy them to `\https:///oauth/authorize`. +`${url}` is replaced with the current URL, escaped to be safe in a query parameter. +`${query}` is replaced with the current query string. +<7> 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. +<8> Optional: list of common names (`cn`). If set, a valid client certificate with +a Common Name (`cn`) in the specified list must be presented before the request headers +are checked for user names. If empty, any Common Name is allowed. Can only be used in combination +with `clientCA`. +<9> Header names to check, in order, for the user identity. The first header containing +a value is used as the identity. Required, case-insensitive. +<10> Header names to check, in order, for an email address. The first header containing +a value is used as the email address. Optional, case-insensitive. +<11> Header names to check, in order, for a display name. The first header containing +a value is used as the display name. Optional, case-insensitive. +<12> Header names to check, in order, for a preferred user name, if different than the immutable +identity determined from the headers specified in `headers`. The first header containing +a value is used as the preferred user name when provisioning. Optional, case-insensitive.