openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

configuring IDP conversion draft

Browse Source
This commit is contained in:
Kathryn Alexander
2019-01-07 12:36:45 -05:00
parent fee2571f8f
commit 9559e1ea42
40 changed files with 2173 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
_topic_map.yml
View File

@@ -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

16
authentication/identity_providers/configuring-allow-all-identity-provider.adoc Normal file
View File

@@ -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]

23
authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc Normal file
View File

@@ -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]

16
authentication/identity_providers/configuring-deny-all-identity-provider.adoc Normal file
View File

@@ -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]

38
authentication/identity_providers/configuring-github-identity-provider.adoc Normal file
View File

@@ -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]

22
authentication/identity_providers/configuring-gitlab-identity-provider.adoc Normal file
View File

@@ -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]

29
authentication/identity_providers/configuring-google-identity-provider.adoc Normal file
View File

@@ -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
`<master>/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]

19
authentication/identity_providers/configuring-htpasswd-identity-provider.adoc Normal file
View File

@@ -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]

31
authentication/identity_providers/configuring-keystone-identity-provider.adoc Normal file
View File

@@ -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]

18
authentication/identity_providers/configuring-ldap-identity-provider.adoc Normal file
View File

@@ -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]

66
authentication/identity_providers/configuring-oidc-identity-provider.adoc Normal file
View File

@@ -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
`<master>/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]

19
authentication/identity_providers/configuring-request-header-identity-provider.adoc Normal file
View File

@@ -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]

82
authentication/understanding-identity-provider.adoc Normal file
View File

@@ -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]

75
modules/identity-provider-about-basic-authentication.adoc Normal file
View File

@@ -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", ...}
----

72
modules/identity-provider-about-ldap.adoc Normal file
View File

@@ -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:
----
(&(<filter>)(<attribute>=<username>))
----
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.

77
modules/identity-provider-about-request-header.adoc Normal file
View File

@@ -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://<master>/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://<master>/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://<master>/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://<master>/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.

42
modules/identity-provider-add.adoc Normal file
View File

@@ -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:

32
modules/identity-provider-allow-all-CRD.adoc Normal file
View File

@@ -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.

42
modules/identity-provider-basic-authentication-CRD.adoc Normal file
View File

@@ -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.

55
modules/identity-provider-basic-authentication-troubleshooting.adoc Normal file
View File

@@ -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 `<user>` and `<password>` 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 <user>:<password> -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"}`

313
modules/identity-provider-configuring-apache-request-header.adoc Normal file
View File

@@ -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://<master>/oauth/authorize` must end with `/authorize` (with no trailing slash). For example:
* `\https://proxy.example.com/login-proxy/authorize?...` -> `\https://<master>/oauth/authorize?...`
6. Subpaths of the URL that proxies to `\https://<master>/oauth/authorize` must proxy to subpaths of `\https://<master>/oauth/authorize`. For example:
* `\https://proxy.example.com/login-proxy/authorize/approve?...` -> `\https://<master>/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.
<VirtualHost *:80>
DocumentRoot /var/www/html
RewriteEngine On
RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R,L]
</VirtualHost>
<VirtualHost *:443>
# 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]
<Location /challenging-proxy/oauth/authorize>
# 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.
</Location>
<Location /login-proxy/oauth/authorize>
# 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
</Location>
</VirtualHost>
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' \
'<masterPublicURL>/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' \
'<redirected challengeURL from step 3 +query>'
----
. 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.

64
modules/identity-provider-configuring-basic-authentication.adoc Normal file
View File

@@ -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=<apiserver> --write-config=<directory>
----
+
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=<path/to/modified/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.

84
modules/identity-provider-configuring-github.adoc Normal file
View File

@@ -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=<apiserver> --write-config=<directory>
----
+
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=<path/to/modified/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.

79
modules/identity-provider-configuring-keystone.adoc Normal file
View File

@@ -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=<apiserver> --write-config=<directory>
----
+
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=<path/to/modified/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.

41
modules/identity-provider-create-CRD.adoc Normal file
View File

@@ -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.

44
modules/identity-provider-creating-htpasswd-file.adoc Normal file
View File

@@ -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 </path/to/users.htpasswd> <user_name> <password>
----
+
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 </path/to/users.htpasswd> <user_name> <password>
----

32
modules/identity-provider-default-CRD.adoc Normal file
View File

@@ -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.

32
modules/identity-provider-deny-all-CRD.adoc Normal file
View File

@@ -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.

68
modules/identity-provider-github-CRD.adoc Normal file
View File

@@ -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
`<master>/oauth2callback/<identityProviderName>`.
<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.

54
modules/identity-provider-gitlab-CRD.adoc Normal file
View File

@@ -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
`<master>/oauth2callback/<identityProviderName>`.
<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.

44
modules/identity-provider-google-CRD.adoc Normal file
View File

@@ -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
`<master>/oauth2callback/<identityProviderName>`.
<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.

35
modules/identity-provider-htpasswd-CRD.adoc Normal file
View File

@@ -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`].

44
modules/identity-provider-keystone-CRD.adoc Normal file
View File

@@ -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.

72
modules/identity-provider-ldap-CRD.adoc Normal file
View File

@@ -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.
====

117
modules/identity-provider-oidc-CRD.adoc Normal file
View File

@@ -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 `<master>/oauth2callback/<identityProviderName>`.
<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`.

26
modules/identity-provider-overview.adoc Normal file
View File

@@ -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.
====

58
modules/identity-provider-parameters.adoc Normal file
View File

@@ -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`.

56
modules/identity-provider-provisioning-user-lookup-mapping.adoc Normal file
View File

@@ -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 <username>
----
+
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 <identity-provider>:<user-id-from-identity-provider>
----
+
The `<identity-provider>` 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 <identity-provider>:<user-id-from-identity-provider> <username>
----
+
For example, the following command maps the identity to the user:
+
----
$ oc create useridentitymapping ldap_provider:bob_s bob
----

35
modules/identity-provider-registering-github.adoc Normal file
View File

@@ -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`:
+
----
<apiserver>/oauth2callback/<identityProviderName>
----
+
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.

74
modules/identity-provider-request-header-CRD.adoc Normal file
View File

@@ -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://<master>/oauth/authorize`.
The URL that proxies to `\https://<master>/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://<master>/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.