diff --git a/_topic_map.yml b/_topic_map.yml index 18da942aef08..69ec64d46061 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -291,6 +291,40 @@ Topics: Distros: openshift-enterprise - Name: Installing a Stand-alone Deployment of OpenShift Container Registry File: stand_alone_registry +- Name: Configuring Authentication + Dir: authentication + Distros: openshift-origin,openshift-enterprise + Topics: + - Name: Overview + File: index + - Name: Configuring OAuth + File: configuring_authentication_identity_provider + - Name: Allow All Authentication + File: configuring_authentication_allow_all + - Name: Deny All Authentication + File: configuring_authentication_deny_all + - Name: HTPasswd Authentication + File: configuring_authentication_htpasswd + - Name: Keystone Authentication + File: configuring_authentication_keystone + - Name: LDAP Authentication + File: configuring_authentication_ldap + - Name: Basic Authentication (Remote) Authentication + File: configuring_authentication_basic_auth + - Name: Request Header Authentication + File: configuring_authentication_request_header + - Name: Github Authentication + File: configuring_authentication_github + - Name: Gitlab Authentication + File: configuring_authentication_gitlab + - Name: Google Authentication + File: configuring_authentication_google + - Name: OpenID Connect Authentication + File: configuring_authentication_openid + - Name: OAuth Options + File: configuring_authentication_oauth_options +- Name: Preventing Access to the APIs + File: configuring_authentication_user_agent - Name: Setting up the Registry Dir: registry Distros: openshift-origin,openshift-enterprise @@ -337,7 +371,6 @@ Topics: File: container_provider - Name: Uninstalling File: uninstalling - - Name: Upgrading a Cluster Dir: upgrading Distros: openshift-origin,openshift-enterprise @@ -516,6 +549,9 @@ Topics: - Name: Deploying External Persistent Volume Provisioners File: provisioners Distros: openshift-origin,openshift-enterprise +- Name: Deploying CloudForms on OpenShift + File: deploying_cfme + Distros: openshift-enterprise - Name: Revision History File: revhistory_install_config Distros: openshift-enterprise diff --git a/admin_guide/manage_users.adoc b/admin_guide/manage_users.adoc index c59db4cc6f0c..d04599fe4f24 100644 --- a/admin_guide/manage_users.adoc +++ b/admin_guide/manage_users.adoc @@ -23,7 +23,7 @@ be deleted. == Adding a User After new users log in to {product-title}, an account is created for that user -per the xref:../install_config/configuring_authentication.adoc#identity-providers[identity +per the xref:../install_config/authentication/index.adoc#identity-providers[identity provider] configured on the master. The cluster administrator can xref:../admin_guide/manage_authorization_policy.adoc#admin-guide-manage-authorization-policy[manage the access level of each user]. diff --git a/admin_solutions/authentication.adoc b/admin_solutions/authentication.adoc index 3f9bc4cdb5d7..6fb3fdc3e55e 100644 --- a/admin_solutions/authentication.adoc +++ b/admin_solutions/authentication.adoc @@ -13,7 +13,7 @@ toc::[] == Overview {product-title} supports many different authentication methods, as defined in -xref:../install_config/configuring_authentication.adoc#install-config-configuring-authentication[Configuring Authentication]: +xref:../install_config/authentication/index.adoc#install-config-configuring-authentication-index[Configuring Authentication]: - xref:basic-auth-remote[Basic Authentication (Remote)] - xref:request-header-auth[Request Header] @@ -84,13 +84,12 @@ If you use the following steps to modify your configuration manually after insta + . Edit the new *_master-config.yaml_* file's `identityProviders` stanza. . Copy -xref:../install_config/configuring_authentication.adoc#basic-auth-example-config[the example `BasicAuthPasswordIdentityProvider` configuration] and paste it to replace the existing stanza. +xref:../install_config/authentication/configuring_authentication_basic_auth.adoc#basic-auth-example-config[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, -xref:../install_config/configuring_authentication.adoc#mapping-identities-to-users[set `mappingMethod`] to control how mappings are established between the +.. 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. @@ -226,16 +225,15 @@ If you use the following steps to modify your configuration manually after insta ==== + . Edit the new *_master-config.yaml_* file's `identityProviders` stanza. -. View -xref:../install_config/configuring_authentication.adoc#reqhead-auth-example-config[the example `RequestHeaderIdentityProvider` configuration] +. View +xref:../install_config/authentication/configuring_authentication_request_header.adoc#reqhead-ww-auth-optional[the example RequestHeaderIdentityProvider configuration] and use it as a guide to replace the existing stanza. . Modify the `identityProviders` stanza based on which headers you plan to pass in. .. 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, -xref:../install_config/configuring_authentication.adoc#mapping-identities-to-users[set `mappingMethod`] +.. If required, set `mappingMethod` to control how mappings are established between the provider's identities and user objects. .. Set the `challenge` parameter to `true` to redirect unauthenticated @@ -243,13 +241,13 @@ requests from clients expecting `WWW-Authenticate` challenges. .. Set the `provider.challengeURL` parameter to the proxy URL to which to send clients expecting `WWW-Authenticate` challenges, like the `oc` CLI client. This parameter can include the -xref:../install_config/configuring_authentication.adoc#RequestHeaderIDP-urlquerytokens[`${url}` and `${query}` tokens] +xref:../install_config/authentication/configuring_authentication_request_header.adoc#requestheaderidp-urlquerytokens[`${url}` and `${query}` tokens] in the query portion of the URL. .. Set the `login` parameter to `true` to redirect unauthenticated requests from clients expecting login flows. .. Set the `provider.loginURL` parameter to the proxy URL to which to send clients expecting login flows, like web browser clients. This parameter can include the -xref:../install_config/configuring_authentication.adoc#RequestHeaderIDP-urlquerytokens[`${url}` and `${query}` tokens] +xref:../install_config/authentication/configuring_authentication_request_header.adoc#requestheaderidp-urlquerytokens[`${url}` and `${query}` tokens] in the query portion of the URL. .. Set the `clientCA` parameter to the certificate bundle to use to check incoming requests for a valid client certificate before the request's headers @@ -360,13 +358,12 @@ If you use the following steps to modify your configuration manually after insta + . Edit the new *_keystoneconfig/master-config.yaml_* file's `identityProviders` stanza. . Copy -xref:../install_config/configuring_authentication.adoc#KeystonePasswordIdentityProvider[the example `KeystonePasswordIdentityProvider` configuration] +xref:../install_config/authentication/configuring_authentication_keystone.adoc#install-config-configuring-authentication-keystone[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, -xref:../install_config/configuring_authentication.adoc#mapping-identities-to-users[change `mappingMethod`] to control how mappings are established between the +.. 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. @@ -419,7 +416,7 @@ xref:../admin_solutions/user_role_mgmt.adoc#control-user-roles[control user role LDAP uses bind operations to authenticate applications, and you can integrate your {product-title} cluster to use LDAPv3 authentication. Configuring LDAP authentication allows users to log in to {product-title} with their LDAP credentials. -include::install_config/configuring_authentication.adoc[tag=ldapblurb] +include::install_config/authentication/configuring_authentication_ldap.adoc[tag=ldapblurb] [WARNING] ==== @@ -479,14 +476,13 @@ If you use the following steps to modify your configuration manually after insta + . Edit the new *_master-config.yaml_* file's `identityProviders` stanza. . Copy -xref:../install_config/configuring_authentication.adoc#ldap-example-config[the example `LDAPPasswordIdentityProvider` configuration] +xref:../install_config/authentication/configuring_authentication_ldap.adoc#ldap-example-config[the example `LDAPPasswordIdentityProvider` configuration] and paste it to replace the existing stanza. . Make the following modifications to the `identityProviders` stanza: .. Change the provider `name` ("my_ldap_provider") to something unique and relevant to your deployment. This name is prefixed to the returned user name to form an identity name. -.. If required, -xref:../install_config/configuring_authentication.adoc#mapping-identities-to-users[change `mappingMethod`] to control how mappings are established between the +.. If required, change `mappingMethod` to control how mappings are established between the provider's identities and user objects. .. Change `id` to the attribute to use as the identity, which must be unique and immutable within the identity provider. This option can accept multiple @@ -527,7 +523,7 @@ connect using TLS, and `ldap://` URLs are upgraded to TLS. When `true`, no TLS connection is made to the server, however, setting this to `true` creates an invalid configuration for LDAP. .. Define an RFC 2255 URL that -xref:../install_config/configuring_authentication.adoc#ldap-url[specifies the LDAP host and search parameters] to use. +xref:../install_config/authentication/configuring_authentication_ldap.adoc#ldap-url[specifies the LDAP host and search parameters] to use. . Save your changes and close the file. . Start the {product-title} API server, specifying the configuration file you just modified: @@ -650,7 +646,7 @@ hostname that web browsers use to interact with your {product-title} cluster. ==== . Edit the new *_master-config.yaml_* file's `identityProviders` stanza. . Copy -xref:../install_config/configuring_authentication.adoc#GitHub[the example `GitHubIdentityProvider` configuration] +xref:../install_config/authentication/configuring_authentication_github.adoc#github-auth-example-config[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 diff --git a/admin_solutions/master_node_config.adoc b/admin_solutions/master_node_config.adoc index 2f07bbecf01b..59696d806a30 100644 --- a/admin_solutions/master_node_config.adoc +++ b/admin_solutions/master_node_config.adoc @@ -238,7 +238,7 @@ You can then use the password file when configuring xref:config-htpasswd[HTPassw [NOTE] ==== -For more information on the `htpasswd` command, see xref:../install_config/configuring_authentication.adoc#HTPasswdPasswordIdentityProvider[HTPasswd Identity Provider]. +For more information on the `htpasswd` command, see xref:../install_config/authentication/configuring_authentication_htpasswd.adoc#install-config-configuring-authentication-htpasswd[Configuring the HTPasswd Identity Provider]. ==== [[master-node-config-manual]] diff --git a/architecture/additional_concepts/authentication.adoc b/architecture/additional_concepts/authentication.adoc index 667d1ba82f2f..41003acdabbb 100644 --- a/architecture/additional_concepts/authentication.adoc +++ b/architecture/additional_concepts/authentication.adoc @@ -17,7 +17,7 @@ requesting user to determine if the request should be allowed. ifdef::openshift-enterprise,openshift-origin[] As an administrator, you can -xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[configure authentication] +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[configure authentication] using a xref:../../install_config/master_node_configuration.adoc#install-config-master-node-configuration[master configuration file]. endif::[] @@ -131,7 +131,7 @@ access tokens to authenticate themselves to the API. When a person requests a new OAuth token, the OAuth server uses the configured ifdef::openshift-enterprise,openshift-origin[] -xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[identity +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[identity provider] endif::[] ifdef::openshift-dedicated[] @@ -184,7 +184,7 @@ grantMethod: prompt <4> <1> The `name` of the OAuth client is used as the `client_id` parameter when making requests to `__/oauth/authorize` and `__/oauth/token`. <2> The `secret` is used as the `client_secret` parameter when making requests to `__/oauth/token`. <3> The `redirect_uri` parameter specified in requests to `__/oauth/authorize` and `__/oauth/token` must be equal to (or prefixed by) one of the URIs in `redirectURIs`. -<4> The `grantMethod` is used to determine what action to take when this client requests tokens and has not yet been granted access by the user. Uses the same values seen in xref:../../install_config/configuring_authentication.adoc#grant-options[Grant Options]. +<4> The `grantMethod` is used to determine what action to take when this client requests tokens and has not yet been granted access by the user. Uses the same values seen in xref:../../install_config/authentication/configuring_authentication_oauth_options.adoc#install-config-configuring-authentication-oauth-grant[Grant Options]. ==== [[service-accounts-as-oauth-clients]] @@ -553,7 +553,7 @@ All requests for OAuth tokens involve a request to `__/oauth/authorize`. Most authentication integrations place an authenticating proxy in front of this endpoint, or configure {product-title} to validate credentials against a backing ifdef::openshift-enterprise,openshift-origin[] -xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[identity +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[identity provider]. endif::[] ifdef::openshift-dedicated[] diff --git a/architecture/additional_concepts/other_api_objects.adoc b/architecture/additional_concepts/other_api_objects.adoc index 0f1cd869c238..3d1b7319f65c 100644 --- a/architecture/additional_concepts/other_api_objects.adoc +++ b/architecture/additional_concepts/other_api_objects.adoc @@ -269,7 +269,7 @@ this token, if any. === Identity When a user logs into {product-title}, they do so using a configured ifdef::openshift-enterprise,openshift-origin[] -xref:../../install_config/configuring_authentication.adoc#identity-providers[identity +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[identity provider]. endif::[] ifdef::openshift-dedicated[] diff --git a/architecture/index.adoc b/architecture/index.adoc index 2c1c2b249bbc..b1411c2c5f5a 100644 --- a/architecture/index.adoc +++ b/architecture/index.adoc @@ -7,6 +7,7 @@ :experimental: :linkattrs: + ifdef::openshift-origin,openshift-online,openshift-enterprise,openshift-dedicated[] OpenShift v3 is a layered system designed to expose underlying Docker-formatted container image and Kubernetes concepts as accurately as possible, with a focus diff --git a/install_config/authentication/configuring_authentication_allow_all.adoc b/install_config/authentication/configuring_authentication_allow_all.adoc new file mode 100644 index 000000000000..551ed653f66e --- /dev/null +++ b/install_config/authentication/configuring_authentication_allow_all.adoc @@ -0,0 +1,141 @@ +[[install-config-configuring-authentication-allow]] += Configuring Allow All Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +{nbsp} + + + +You can configure the {product-title} master configuration file to use Allow All authentication in your cluster. + +[[install-config-configuring-authentication-allow-intro]] +== Configuring the Allow All Identity Provider + +Setting the `AllowAllPasswordIdentityProvider` in the `identityProviders` stanza allows any non-empty user name and password to log in. This is the default +identity provider when running {product-title} without a +xref:../../install_config/master_node_configuration.adoc#install-config-master-node-configuration[master configuration file]. + +To configure the Allow All identity provider: + +//tag::configuring_authentication_common_steps1[] + +. Edit the master configuration file: ++ +---- +/etc/origin/master/master-config.yaml +---- + +. Set the following parameters, as needed, or use the default values: ++ +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true +---- ++ +[cols="2a,8a",options="header"] +|=== +|Parameter | Description +|`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`. This provider selection page can be +xref:../../install_config/web_console_customization.adoc#customizing-the-login-page[customized]. +|=== +//end::configuring_authentication_common_steps1[] + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +//tag::configuring_authentication_common_steps2[] ++ +---- +oauthConfig: + ... + identityProviders: + - mappingMethod: claim +---- ++ +[cols="2,8"] +|=== +|Parameter | Description + +|`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. For more information on provisioning users with the `lookup` method, +see xref:../../install_config/authentication/configuring_authentication_mapping_method.adoc#install-config-configuring-authentication-lookup[Manually Provisioning a User When Using the Lookup Mapping Method]. + +|`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. +|=== +//end::configuring_authentication_common_steps2[] + +. Specify the following values to configure the Allow All provider: ++ +.Master Configuration Using `AllowAllPasswordIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_allow_provider <1> + provider: + apiVersion: v1 + kind: AllowAllPasswordIdentityProvider <2> +---- +<1> This provider name is prefixed to provider user names to form an identity +name. +<2> Specify *_AllowAllPasswordIdentityProvider_* as the provider kind. +==== +//tag::restart-after-config-master[] +. Restart the {product-title} service. ++ +ifdef::openshift-enterprise[] +---- +# systemctl restart atomic-openshift-master +---- +endif::[] +ifdef::openshift-origin[] +---- +# systemctl restart origin-master +---- +endif::[] +//end::restart-after-config-master[] + + diff --git a/install_config/authentication/configuring_authentication_basic_auth.adoc b/install_config/authentication/configuring_authentication_basic_auth.adoc new file mode 100644 index 000000000000..68714813f2de --- /dev/null +++ b/install_config/authentication/configuring_authentication_basic_auth.adoc @@ -0,0 +1,118 @@ +[[install-config-configuring-authentication-basic]] += Configuring Basic Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + + +{nbsp} + + + +You can configure the {product-title} master configuration file to use Basic authentication in your cluster. + +== Configuring the Basic Authentication (Remote) Identity Provider + +Set `BasicAuthPasswordIdentityProvider` in the `*identityProviders*` stanza to +validate user names and passwords against a remote server using a +server-to-server Basic authentication request. User names and passwords are +validated against a remote URL that is protected by Basic authentication and +returns JSON. + +For information on Basic authentication responses, see xref:configuring_authentication_basic_auth_messages[Understanding Basic Authentication Messages]. + +To configure the Basic Authentication identity provider: + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps1] + +. Specify the `*mappingMethod*` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Specify the following values to configure Basic authentication: ++ +[[basic-auth-example-config]] +.Master Configuration Using `BasicAuthPasswordIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_remote_basic_auth_provider <1> + provider: + apiVersion: v1 + kind: BasicAuthPasswordIdentityProvider <2> + url: https://www.example.com/remote-idp <3> + ca: /path/to/ca.file <4> + certFile: /path/to/client.crt <5> + keyFile: /path/to/client.key <6> +---- +<1> This provider name is prefixed to the returned user ID to form an identity +name. +<2> Specify *_BasicAuthPasswordIdentityProvider_* as the provider kind. +<3> URL accepting credentials in Basic authentication headers. +<4> Optional: Certificate bundle to use to validate server certificates for the +configured URL. +<5> Optional: Client certificate to present when making requests to the +configured URL. +<6> Key for the client certificate. Required if `certFile` is specified. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + +[discrete] +[[configuring_authentication_basic_auth_messages]] +== Understanding Basic Authentication Messages + +If the authentication is successful: + +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 may optionally provide additional data, such as: + +* A display name using the `name` key. For example: ++ +---- +{"sub":"userid", "name": "User Name", ...} +---- ++ +* An email address using the `email` key. For example: ++ +---- +{"sub":"userid", "email":"user@example.com", ...} +---- ++ +* A preferred user name using the `preferred_username` key. This is useful when +the unique, unchangeable subject is a database key or UID, and a more +human-readable name exists. This is used as a hint when provisioning the +{product-title} user for the authenticated identity. For example: ++ +---- +{"sub":"014fbff9a07c", "preferred_username":"bob", ...} +---- + +If the authentication fails: + +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/install_config/authentication/configuring_authentication_deny_all.adoc b/install_config/authentication/configuring_authentication_deny_all.adoc new file mode 100644 index 000000000000..3900cdbf146c --- /dev/null +++ b/install_config/authentication/configuring_authentication_deny_all.adoc @@ -0,0 +1,52 @@ +[[install-config-configuring-authentication-deny]] += Configuring Deny All Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +{nbsp} + + + +You can configure the {product-title} master configuration file to use Deny All All authentication in your cluster. + +== Configuring the Deny All Identity Provider + +Set `DenyAllPasswordIdentityProvider` in the `identityProviders` stanza to +deny access for all user names and passwords. + + +To configure the Deny All identity provider: + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps1] + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Specify the following values to configure Deny All authentication: ++ +.Master Configuration Using `DenyAllPasswordIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_deny_provider <1> + provider: + apiVersion: v1 + kind: DenyAllPasswordIdentityProvider<2> +---- +<1> This provider name is prefixed to provider user names to form an identity +name. +<2> Specify *_DenyAllPasswordIdentityProvider_* as the provider kind. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] diff --git a/install_config/authentication/configuring_authentication_github.adoc b/install_config/authentication/configuring_authentication_github.adoc new file mode 100644 index 000000000000..cfe4c41290cd --- /dev/null +++ b/install_config/authentication/configuring_authentication_github.adoc @@ -0,0 +1,117 @@ +[[install-config-configuring-authentication-github]] += Configuring GitHub Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + + +{nbsp} + + + +You can configure the {product-title} master configuration file to use GitHub authentication in your cluster. + +== Configuring the GitHub Identity Provider + +Set `GitHubIdentityProvider` in the `identityProviders` stanza to use +link:https://github.com/[GitHub] as an identity provider, using the +link:https://developer.github.com/v3/oauth/[OAuth integration]. + +[NOTE] +==== +Using GitHub as an identity provider requires users to get a token using +`/oauth/token/request` to use with command-line tools. +==== + +[WARNING] +==== +Using GitHub as an identity provider allows any GitHub user to authenticate to your server. +You can limit authentication to members of specific GitHub organizations with the +`organizations` configuration attribute, as shown below. +==== + +To configure the GitHub identity provider: + +. Edit the master configuration file: ++ +---- +/etc/origin/master/master-config.yaml +---- + +. Set the `challenge` parameter to `false`. ++ +---- +oauthConfig: + ... + identityProviders: + - challenge: false + login: true +---- ++ +The GitHub identity provider cannot be used to send `WWW-Authenticate` challenges. + +. Set the `login` parameter to `true`. + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Set the `name` parameter to an appropriate string. ++ +---- +name: github +---- ++ +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. + +. Specify the following values to configure GitHub authentication: ++ +[[github-auth-example-config]] +.Master Configuration Using `GitHubIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: false + login: true + mappingMethod: claim + name: github + provider: + apiVersion: v1 + kind: GitHubIdentityProvider + clientID: ... <1> + clientSecret: ... <2> + organizations: <3> + - myorganization1 + - myorganization2 + teams: <4> + - myorganization1/team-a + - myorganization2/team-b +---- +<1> 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/`. +<2> The client secret issued by GitHub. This value may also be provided in an +xref:../../install_config/master_node_configuration.adoc#master-node-configuration-passwords-and-other-data[environment +variable, external file, or encrypted file]. +<3> 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 log in by the organization's administrator, or from the GitHub organization settings. +Cannot be used in combination with the `teams` field. +<4> 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. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] diff --git a/install_config/authentication/configuring_authentication_gitlab.adoc b/install_config/authentication/configuring_authentication_gitlab.adoc new file mode 100644 index 000000000000..05ee021dab9a --- /dev/null +++ b/install_config/authentication/configuring_authentication_gitlab.adoc @@ -0,0 +1,82 @@ +[[install-config-configuring-authentication-gitlab]] += Configuring GitLab Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + + +{nbsp} + + +You can configure the {product-title} master configuration file to use GitLab authentication in your cluster. + +== Configuring the GitLab Identity Provider + +Set `GitLabIdentityProvider` in the `identityProviders` stanza to use +link:https://gitlab.com/[GitLab.com] or any other GitLab instance as an identity provider, using the +link:http://doc.gitlab.com/ce/integration/oauth_provider.html[OAuth integration]. +The OAuth provider feature requires GitLab version 7.7.0 or higher. + +[NOTE] +==== +Using GitLab as an identity provider requires users to get a token using +`/oauth/token/request` to use with command-line tools. +==== + +To configure the GitLab identity provider: + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps1] + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Set the `name` parameter to an appropriate string. ++ +---- +name: gitlab +---- ++ +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. + +. Specify the following values to configure GitLab authentication: ++ +.Master Configuration Using `GitLabIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - + challenge: true + login: true + mappingMethod: claim + name: gitlab + provider: + apiVersion: v1 + kind: GitLabIdentityProvider <1> + url: ... <2> + clientID: ... <3> + clientSecret: ... <4> + ca: ... <5> +---- +<1> Specify *_GitLabIdentityProvider_* for the provider name. +<2> The host URL of a GitLab OAuth provider. This could either be `\https://gitlab.com/` +or any other self hosted instance of GitLab. +<3> The client ID of a +link:https://gitlab.com/oauth/applications/new[registered GitLab OAuth +application]. The application must be configured with a callback URL of +`/oauth2callback/`. +<4> The client secret issued by GitLab. This value may also be provided in an +xref:../../install_config/master_node_configuration.adoc#master-node-configuration-passwords-and-other-data[environment +variable, external file, or encrypted file]. +<5> 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. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + diff --git a/install_config/authentication/configuring_authentication_google.adoc b/install_config/authentication/configuring_authentication_google.adoc new file mode 100644 index 000000000000..83316a1597ba --- /dev/null +++ b/install_config/authentication/configuring_authentication_google.adoc @@ -0,0 +1,106 @@ +[[install-config-configuring-authentication-google]] += Configuring Google Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +{nbsp} + + + +You can configure the {product-title} master configuration file to use Google authentication in your cluster. + +== Configuring the Google Identity Provider + +Set `GoogleIdentityProvider` in the `*identityProviders*` stanza to use Google +as an 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, as shown below. +==== + +To configure the Google identity provider: + +. Edit the master configuration file: ++ +---- +/etc/origin/master/master-config.yaml +---- + +. Set the `challenge` parameter to `false`. ++ +---- +oauthConfig: + ... + identityProviders: + - challenge: false + login: true +---- ++ +The Google identity provider cannot be used to send `WWW-Authenticate` challenges. + +. Set the `login` parameter to `true`. + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Set the `name` parameter to an appropriate string. ++ +---- +name: google +---- ++ +This provider name is prefixed to the Google numeric user ID to form an identity name. It is also used to build the callback URL. + + +. Specify the following values to configure Google authentication: ++ +.Master Configuration Using `GoogleIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: false + login: true + mappingMethod: claim + name: google + provider: + apiVersion: v1 + kind: GoogleIdentityProvider <1> + clientID: ... <2> + clientSecret: ... <3> + hostedDomain: "" <4> +---- +<1> Specify `GoogleIdentityProvider` for the provider kind. +<2> 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/`. +<3> The client secret issued by Google. This value may also be provided in an +xref:../../install_config/master_node_configuration.adoc#master-node-configuration-passwords-and-other-data[environment +variable, external file, or encrypted file]. +<4> 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. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + + diff --git a/install_config/authentication/configuring_authentication_htpasswd.adoc b/install_config/authentication/configuring_authentication_htpasswd.adoc new file mode 100644 index 000000000000..52d5f977de9b --- /dev/null +++ b/install_config/authentication/configuring_authentication_htpasswd.adoc @@ -0,0 +1,128 @@ +[[install-config-configuring-authentication-htpasswd]] += Configuring HTPasswd Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + + +toc::[] + +== Overview + +You can configure the {product-title} master configuration file to use the HTPassword identity provider for authentication within your cluster. + +== Configuring the HTPasswd Identity Provider + +Set `HTPasswdPasswordIdentityProvider` in the `identityProviders` stanza to +validate user names and passwords against a flat file generated using +link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. + +{product-title} supports the Bcrypt, SHA-1, and MD5 cryptographic hash +functions. MD5 is the default for `htpasswd`. Plaintext, encrypted text, and +other hash functions are not currently supported. + +For information on creating the required HTPasswd user name and password file, see xref:config_auth_using_htpasswd[Using the `htpasswd` Command] below. + +To configure the HTPasswd identity provider: + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps1] + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Specify the following values to configure HTPasswd authentication: ++ +.Master Configuration Using `HTPasswdPasswordIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_htpasswd_provider <1> + provider: + apiVersion: v1 + kind: HTPasswdPasswordIdentityProvider <2> + file: /path/to/users.htpasswd <3> +---- +<1> This provider name is prefixed to provider user names to form an identity +name. +<2> Specify *_HTPasswdPasswordIdentityProvider_* as the provider kind. +<3> File generated using `htpasswd`. See xref:config_auth_using_htpasswd[Using the `htpasswd` Command] in the following section. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + + +[[config_auth_using_htpasswd]] +== Using the `htpasswd` Command + +If necessary, download the `http-tools` package to install the `htpasswd` utility. + +---- +# yum install httpd-tools +---- + +To use the htpasswd command: + +// tag::htpasswd[] + +* To create a flat file with a user name and password, execute the following command: ++ +---- +$ htpasswd -c +---- ++ +Then, enter and confirm a clear-text password for the user. The command generates a file with a hashed version of the password. ++ +For example: ++ +---- +htpasswd -c users.htpasswd user1 +New password: +Re-type new password: +Adding password for user user1 +---- ++ +---- +cat users.htpasswd +admin:$apr1$CSTJyOhm.ZfUGuwp3h0 +user1:$apr1$SBjNoyoBnYPgZM0fCkh. +---- ++ +[NOTE] +==== +You can include the `-b` option to supply the password on the command line: + +---- +$ htpasswd -c -b +---- + +For example: +---- +$ htpasswd -c -b file user1 MyPassword! +Adding password for user user1 +---- +==== + +// end::htpasswd[] + +* To add users to, or update existing users in, the *_users.htpasswd_* file, execute: ++ +---- +$ htpasswd +---- + +* To remove a user from the file, execute: ++ +---- +$ htpasswd -D +---- diff --git a/install_config/authentication/configuring_authentication_identity_provider.adoc b/install_config/authentication/configuring_authentication_identity_provider.adoc new file mode 100644 index 000000000000..24ee5e9b7535 --- /dev/null +++ b/install_config/authentication/configuring_authentication_identity_provider.adoc @@ -0,0 +1,91 @@ +[[install-config-configuring-authentication-provider]] += OAuth Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +toc::[] + +== Overview + +As an administrator, you can configure the specific OAuth identity provider to use for user access and can set OAuth token, grant, and session options. + + +== Configuring OAuth Identity Proviers + +[[identity-providers]] +As an administrator, you can configure OAuth using the +xref:../../install_config/master_node_configuration.adoc#install-config-master-node-configuration[master configuration file] to specify an +xref:identity-providers[identity provider]. +This can be done during an +xref:../../install_config/install/advanced_install.adoc#configuring-cluster-variables[advanced installation] or configured after installation. + +If you installed {product-title} using +the +ifdef::openshift-enterprise[] +xref:../../install_config/install/quick_install.adoc#install-config-install-quick-install[Quick Installation] or +endif::[] +xref:../../install_config/install/advanced_install.adoc#install-config-install-advanced-install[Advanced Installation] +method, the +ifdef::openshift-enterprise[] +xref:../../install_config/authentication/configuring_authentication_deny_all.adoc#install-config-configuring-authentication-deny[Deny All] identity provider, which denies access for all user names and +passwords, is +used by default. To allow access, you must choose a different identity provider and +configure the master configuration file appropriately (located at +*_/etc/origin/master/master-config.yaml_* by default). +endif::[] +ifdef::openshift-origin[] +xref:../../install_config/authentication/configuring_authentication_allow_all.adoc#install-config-configuring-authentication-allow[Allow All] identity provider is +used by default, which allows access for all user names and +passwords. +endif::[] + +When running a master without a configuration file, the +xref:../../install_config/authentication/configuring_authentication_allow_all.adoc#install-config-configuring-authentication-allow[Allow All] identity provider is used by +default, which allows any non-empty user name and password to log in. This is +useful for testing purposes. To use other identity providers, or to modify any +xref:../../install_config/authentication/configuring_authentication_oauth_options.adoc#install-config-configuring-authentication-oauth[token, grant, or session options], you must run the master from a +configuration file. + +[NOTE] +==== +xref:../../architecture/additional_concepts/authorization.adoc#roles[Roles] need +to be assigned to administer the setup with an external user. +==== + +{product-title} supports the following identity providers: + +- xref:../../install_config/authentication/configuring_authentication_allow_all.adoc#install-config-configuring-authentication-allow[Allow All] + +- xref:../../install_config/authentication/configuring_authentication_deny_all.adoc#install-config-configuring-authentication-deny[Deny All] + +- xref:../../install_config/authentication/configuring_authentication_htpasswd.adoc#install-config-configuring-authentication-htpasswd[HTPasswd] + +- xref:../../install_config/authentication/configuring_authentication_keystone.adoc#install-config-configuring-authentication-keystone[Keystone] + +- xref:../../install_config/authentication/configuring_authentication_ldap.adoc#install-config-configuring-authentication-ldap[LDAP] + +- xref:../../install_config/authentication/configuring_authentication_basic_auth.adoc#install-config-configuring-authentication-basic[Basic Authentication (Remote)] + +- xref:../../install_config/authentication/configuring_authentication_request_header.adoc#install-config-configuring-authentication-request[Request Header] + +- xref:../../install_config/authentication/configuring_authentication_github.adoc#install-config-configuring-authentication-github[GitHub] + +- xref:../../install_config/authentication/configuring_authentication_gitlab.adoc#install-config-configuring-authentication-gitlab[GitLab] + +- xref:../../install_config/authentication/configuring_authentication_google.adoc#install-config-configuring-authentication-google[Google] + +- xref:../../install_config/authentication/configuring_authentication_openid.adoc#install-config-configuring-authentication-openid[OpenID Connect] + + +== Configuring OAuth Options + +Set OAuth token, grant, and session options. + +- xref:../../install_config/authentication/configuring_authentication_oauth_options.adoc#install-config-configuring-authentication-oauth[Configuring OAuth Options] + diff --git a/install_config/authentication/configuring_authentication_keystone.adoc b/install_config/authentication/configuring_authentication_keystone.adoc new file mode 100644 index 000000000000..bd5f1410127a --- /dev/null +++ b/install_config/authentication/configuring_authentication_keystone.adoc @@ -0,0 +1,67 @@ +[[install-config-configuring-authentication-keystone]] += Configuring Keystone Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + + +{nbsp} + + + + +You can configure the {product-title} master configuration file to use the Keystone identity provider for authentication within your cluster. + +== Configuring the Keystone Identity Provider + + +Set `KeystonePasswordIdentityProvider` in the `identityProviders` stanza to +validate user names and passwords against an OpenStack Keystone v3 server. +This enables shared authentication with an OpenStack server configured to store +users in an internal Keystone database. + +To configure the Keystone identity provider: + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps1] + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Specify the following values to configure Keystone authentication: ++ +.Master Configuration Using `KeystonePasswordIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_keystone_provider <1> + provider: + apiVersion: v1 + kind: KeystonePasswordIdentityProvider <2> + domainName: default <3> + url: http://keystone.example.com:5000 <4> + ca: ca.pem <5> + certFile: keystone.pem <6> + keyFile: keystonekey.pem <7> +---- +<1> This provider name is prefixed to provider user names to form an identity name. +<2> Specify *_KeystonePasswordIdentityProvider_* for the provider kind. +<3> Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is supported. +<4> The URL to use to connect to the Keystone server (required). +<5> Optional: Certificate bundle to use to validate server certificates for the configured URL. +<6> Optional: Client certificate to present when making requests to the configured URL. +<7> Key for the client certificate. Required if `certFile` is specified. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + + diff --git a/install_config/authentication/configuring_authentication_ldap.adoc b/install_config/authentication/configuring_authentication_ldap.adoc new file mode 100644 index 000000000000..98185bc703e6 --- /dev/null +++ b/install_config/authentication/configuring_authentication_ldap.adoc @@ -0,0 +1,169 @@ +[[install-config-configuring-authentication-ldap]] += Configuring LDAP Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + + +toc::[] + +== Overview + +You can configure the {product-title} master configuration file to use the LDAP (Lightweight Directory Access Protocol) identity provider for authentication within your cluster. + +== Configuring the LDAP Identity Provider + +Set `LDAPPasswordIdentityProvider` in the `identityProviders` stanza to +validate user names and passwords against an LDAPv3 server, using simple bind +authentication. + +For information on using LDAP, see xref:ldap-identity-provider-using[Using LDAP with {product-title}] below. + +To configure the LDAP identity provider: + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps1] + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Specify the following values to configure LDAP authentication: ++ +[[ldap-example-config]] +.Master Configuration Using `LDAPPasswordIdentityProvider` +==== +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: "my_ldap_provider" <1> + provider: + apiVersion: v1 + kind: LDAPPasswordIdentityProvider <2> + attributes: <3> + id: <4> + - dn + email: <5> + - mail + name: <6> + - cn + preferredUsername: <7> + - uid + bindDN: "" <8> + bindPassword: "" <9> + ca: my-ldap-ca-bundle.crt <10> + insecure: false <11> + url: "ldap://ldap.example.com/ou=users,dc=acme,dc=com?uid" <11> +---- +<1> This provider name is prefixed to the returned user ID to form an identity +name. +<2> Specify *_LDAPPasswordIdentityProvider_* as the provider kind. +<3> 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 attributes has a +value, authentication fails. +<4> The unique id of the user, this is being mapped to the dn field in ldap +<5> List of attributes to use as the email address. First non-empty attribute is +used. +<6> List of attributes to use as the display name. First non-empty attribute is +used. +<7> List of attributes to use as the preferred user name when provisioning a +user for this identity. First non-empty attribute is used. +<8> Optional DN to use to bind during the search phase. +<9> Optional password to use to bind during the search phase. This value may also be +provided in an +xref:../../install_config/master_node_configuration.adoc#master-node-configuration-passwords-and-other-data[environment +variable, external file, or encrypted file]. +<10> Certificate bundle to validate server certificates for the +configured URL. If empty, system trusted roots are used. Only applies if +`insecure: false`. +<11> When `true`, no TLS connection is made to the server. When `false`, +`ldaps://` URLs connect using TLS, and `ldap://` URLs are upgraded to TLS. +<11> An RFC 2255 URL which specifies the LDAP host and search parameters to use, +xref:ldap-url[as described above]. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + + +[[ldap-identity-provider-using]] +== Using LDAP with {product-title} + +// tag::ldapblurb[] + +During authentication, {product-title} searches the LDAP directory 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. If the search does not return exactly one entry, access is denied. + +// end::ldapblurb[] + + +When using LDAP, {product-title}: + +. generates a search filter by combining the attribute and filter in the +configured `url` with the user-provided user name; +. searches the directory using the generated filter; +. attempts 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 successful, {product-title} builds an identity using the configured attributes +as the identity, email address, display name, and preferred user name. +.. If the bind is unsuccessful, {product-title} denies access. + +[[ldap-url]] +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 the above example: + +[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 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/install_config/authentication/configuring_authentication_mapping_method.adoc b/install_config/authentication/configuring_authentication_mapping_method.adoc new file mode 100644 index 000000000000..8fa55eb478a2 --- /dev/null +++ b/install_config/authentication/configuring_authentication_mapping_method.adoc @@ -0,0 +1,64 @@ +[[install-config-configuring-authentication-lookup]] += Manually Provisioning a User When Using the Lookup Mapping Method +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +{nbsp} + + + +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. + +For more information on identity objects, see the xref:../architecture/additional_concepts/other_api_objects.adoc#identity[Identity] +user API obejct. + +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/install_config/authentication/configuring_authentication_oauth_options.adoc b/install_config/authentication/configuring_authentication_oauth_options.adoc new file mode 100644 index 000000000000..3f71e5733216 --- /dev/null +++ b/install_config/authentication/configuring_authentication_oauth_options.adoc @@ -0,0 +1,152 @@ +[[install-config-configuring-authentication-oauth]] += Configuring OAuth Token, Grant, and Session Options +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +{nbsp} + + + +You can configure token, grant and session options for the OAuth deployment in your cluster. + +== Configuring OAuth Options + +When configuring OAuth, you can specify the following: + +* Token options. The OAuth server generates two kinds of tokens: ++ +** Access tokens. Longer-lived tokens that grant access to the API. + +** Authorize codes. Short-lived tokens whose only use is to be exchanged for +an access token. + +* Grant options. When the OAuth server receives token requests for a client to which the user +has not previously granted permission, the action that the OAuth server takes +is dependent on the OAuth client's grant strategy. ++ +When the OAuth client requesting token does not provide its own grant strategy, +the server-wide default strategy is used. To configure the default strategy, +set the `method` value in the `grantConfig` stanza. + +* Session Options. The OAuth server uses a signed and encrypted cookie-based session during login +and redirect flows. ++ +Use the `sessionConfig` stanza to set session options: ++ +** maximum age of a session +** name of the cookie used +** file name of the serialized SessionSecrets object + + + +To configure OAuth: + +. Edit the master configuration file: ++ +---- +/etc/origin/master/master-config.yaml +---- + +. Use the `tokenConfig` stanza to set token options, as needed: ++ +.Master Configuration Token Options +==== + +---- +oauthConfig: + ... + tokenConfig: + accessTokenMaxAgeSeconds: 86400 <1> + authorizeTokenMaxAgeSeconds: 300 <2> +---- +<1> Set `accessTokenMaxAgeSeconds` to control the lifetime of access tokens. +The default lifetime is 24 hours. +<2> Set `authorizeTokenMaxAgeSeconds` to control the lifetime of authorize +codes. The default lifetime is five minutes. +==== +[[install-config-configuring-authentication-oauth-grant]] +. Use the `grantConfig` stanza to set grant options, as needed: ++ +.Master Configuration Grant Options +==== + +---- +oauthConfig: + ... + grantConfig: + method: auto +---- +==== ++ +Valid values for `method` are: ++ +* `auto`. Auto-approve the grant and retry the request. +* `prompt`. Prompt the user to approve or deny the grant. +* `deny`. Auto-deny the grant and return a failure error to the client. + +. Use the `sessionConfig` stanza to configure session options: ++ +.Master Configuration Session Options +==== +---- +oauthConfig: + ... + sessionConfig: + sessionMaxAgeSeconds: 300 <1> + sessionName: ssn <2> + sessionSecretsFile: "..." <3> +---- + +<1> Controls the maximum age of a session; sessions auto-expire once a token request is complete. If auto-grant is not enabled, sessions must last as long as the user is expected to take to approve or reject a client authorization request. +<2> Name of the cookie used to store the session. +<3> File name containing serialized SessionSecrets object. If empty, a random signing and encryption secret is generated at each server start. +==== + +. Use the `secrets` stanza to set session secret options, as needed: ++ +.Master Configuration Session Secret Options: +==== + +---- +apiVersion: v1 +kind: SessionSecrets +secrets: <1> +- authentication: "..." <2> + encryption: "..." <3> +- authentication: "..." + encryption: "..." +... +---- +<1> List of secrets used to authenticate and encrypt cookie sessions. At least +one secret must be specified. Each secret must set an authentication and +encryption secret. +<2> Signing secret, used to authenticate sessions using HMAC. Recommended to use +a secret with 32 or 64 bytes. +<3> Encrypting secret, used to encrypt sessions. Must be 16, 24, or 32 +characters long, to select AES-128, AES-192, or AES-256. +==== ++ +To specify the signing and encryption secret to use, specify a +`sessionSecretsFile`. This allows you separate secret values from the +configuration file and keep the configuration file distributable, for example +for debugging purposes. ++ +Multiple secrets can be specified in the `sessionSecretsFile` to enable +rotation. New sessions are signed and encrypted using the first secret in the +list. Existing sessions are decrypted and authenticated by each secret until one +succeeds. ++ +If no `sessionSecretsFile` is specified, a random signing and encryption +secret is generated at each start of the master server. This means that any +logins in progress will have their sessions invalidated if the master is +restarted. It also means that if multiple masters are configured, they will not +be able to decode sessions generated by one of the other masters. + + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + diff --git a/install_config/authentication/configuring_authentication_openid.adoc b/install_config/authentication/configuring_authentication_openid.adoc new file mode 100644 index 000000000000..9208abd62f28 --- /dev/null +++ b/install_config/authentication/configuring_authentication_openid.adoc @@ -0,0 +1,203 @@ +[[install-config-configuring-authentication-openid]] += Configuring OpenID Connect Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +toc::[] + +== Overview + +You can configure the {product-title} master configuration file to use the OpenID Connect identity provider for authentication within your cluster. + +== Configuring the OpenID Connect Identity Provider + +Set `OpenIDIdentityProvider` in the `identityProviders` stanza to integrate +with an OpenID Connect identity provider using an +link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]. + +[NOTE] +==== +`ID Token` and `UserInfo` decryptions are not supported. +==== + +By default, the `openid` scope is requested. If required, extra scopes can be +specified in the `extraScopes` field. + +Claims are read from the JWT `id_token` returned from the OpenID identity +provider and, if specified, from the JSON returned by the `UserInfo` URL. + +[NOTE] +==== +Using an OpenID Connect identity provider requires users to get a token using +`/oauth/token/request` to use with command-line tools. +==== + +Configure either of the following: + +* xref:open_id_connect_standard[Standard Master Configuration] +* xref:open_id_connect_full[Full Master Configuration] + +[[open_id_connect_standard]] +=== Configuring Standard Master Configuration + +To configure the standard OpenID Connect identity provider: + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps1] + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Set the name parameter to an appropriate string. This provider name is prefixed to provider user names to form an identity name and is used to build the redirect URL. ++ +---- +name: my_ww_authenticate_provider +---- + +. Specify the following values to configure OpenID authentication: ++ +.Standard Master Configuration Using `OpenIDIdentityProvider` +==== +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_openid_connect + provider: + apiVersion: v1 + kind: OpenIDIdentityProvider <1> + clientID: ... <2> + clientSecret: ... <3> + claims: + id: + - sub <4> + preferredUsername: + - preferred_username + name: + - name + email: + - email + urls: + authorize: https://myidp.example.com/oauth2/authorize <5> + token: https://myidp.example.com/oauth2/token <6> +---- +<1> Specify `OpenIDIdentityProvider` as provider kind. +<2> The client ID of a client registered with the OpenID provider. The client +must be allowed to redirect to `/oauth2callback/`. +<3> The client secret. This value may also be provided in an +xref:../../install_config/master_node_configuration.adoc#master-node-configuration-passwords-and-other-data[environment +variable, external file, or encrypted file]. +<4> Use the value of the `sub` claim in the returned `id_token` as the user's +identity. +<5> link:http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint[Authorization Endpoint] +described in the OpenID spec. Must use `https`. +<6> link:http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint[Token Endpoint] +described in the OpenID spec. Must use `https`. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + +[[open_id_connect_full]] +=== Configuring Full Master Configuration + +A custom certificate bundle, extra scopes, extra authorization request +parameters, and `userInfo` URL can also be specified. + +To configure the full OpenID Connect identity provider: + +. Edit the master configuration file: ++ +---- +/etc/origin/master/master-config.yaml +---- + +. Set the `challenge` parameter to `false`. ++ +---- +oauthConfig: + ... + identityProviders: + - challenge: false +---- + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Set the name parameter to an appropriate string. This provider name is prefixed to provider user names to form an identity name and is used to build the redirect URL. ++ +---- +name: my_ww_authenticate_provider +---- + +. Specify the following values to configure OpenID authentication: + ++ +.Full Master Configuration Using `OpenIDIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: false + login: true + mappingMethod: claim + name: my_openid_connect + provider: + apiVersion: v1 + kind: OpenIDIdentityProvider <1> + clientID: ... + clientSecret: ... + ca: my-openid-ca-bundle.crt <2> + extraScopes: <3> + - email + - profile + extraAuthorizeParameters: <4> + include_granted_scopes: "true" + claims: + id: <5> + - custom_id_claim + - sub + preferredUsername: <6> + - preferred_username + - email + name: <7> + - nickname + - given_name + - name + email: <8> + - 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 <9> +---- +<1> Specify `OpenIDIdentityProvider` as provider kind. +<2> Certificate bundle to use to validate server certificates for the configured +URLs. If empty, system trusted roots are used. +<3> Optional list of scopes to request, in addition to the `openid` scope, +during the authorization token request. +<4> Optional map of extra parameters to add to the authorization token request. +<5> List of link:http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[claims] to use as the identity. 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. At least one claim is required. If none of the listed claims have a value, +authentication fails. +<6> List of claims to use as the preferred user name when provisioning a user +for this identity. First non-empty claim is used. +<7> List of claims to use as the display name. First non-empty claim is used. +<8> List of claims to use as the email address. First non-empty claim is used. +<9> link:http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] described in the OpenID spec. Must use `https`. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + diff --git a/install_config/authentication/configuring_authentication_request_header.adoc b/install_config/authentication/configuring_authentication_request_header.adoc new file mode 100644 index 000000000000..12c59cbdb86d --- /dev/null +++ b/install_config/authentication/configuring_authentication_request_header.adoc @@ -0,0 +1,536 @@ +[[install-config-configuring-authentication-request]] += Configuring Request Header Authentication +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +toc::[] + +== Overview + +You can configure the {product-title} master configuration file to use the Request Header identity provider for authentication within your cluster. + +== Configuring the Request Header Identity Provider + +Set `RequestHeaderIdentityProvider` in the `identityProviders` stanza to +identify users from request header values, such as `X-Remote-User`. It is +typically used in combination with an xref:RequestHeaderIdentityProviderProxy[authenticating proxy], which sets the +request header value. + +Perform either of the following changes on the master node. + +* xref:redirect-www-challenges[Redirect unauthenticated requests from clients expecting `WWW-Authenticate` challenges.] +* xref:redirect-browser-based-requests[Redirect unauthenticated requests from clients expecting browser-based login flows.] + + +[[redirect-www-challenges]] +=== Configuring for WWW-Authenticate Challenges + +To redirect unauthenticated requests from clients expecting `WWW-Authenticate` challenges. + +. Edit the master configuration file using the xref:reqhead-ww-auth-optional[example below]: ++ +---- +/etc/origin/master/master-config.yaml +---- + +. Set the `challenge` parameter to `true`. ++ +---- +oauthConfig: + ... + identityProviders: + - challenge: true +---- ++ +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. + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Set the `name` parameter to an appropriate string. This provider name is prefixed to provider user names to form an identity name. ++ +---- +name: my_ww_authenticate_provider +---- + +. 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`. ++ +[[requestheaderidp-urlquerytokens]] +The `provider.challengeURL` parameters can include +the following tokens in the query portion of the URL: ++ +// tag::IDP-urlquerytokens[] +*** `${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. +==== +// end::IDP-urlquerytokens[] ++ +.Master Configuration Using `WW-Authenticate` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_ww_authenticate_provider + provider: + apiVersion: v1 + kind: RequestHeaderIdentityProvider <1> + challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" <2> +---- +<1> Specify *_RequestHeaderIdentityProvider_* as the provider kind. +<2> 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. + +==== + +. In the *_provider_* stanza, specify the header names to check, in order, for the user identity. The first header containing +a value is used as the identity. This parameter is case-insensitive. ++ +---- + provider: + headers: + - X-Remote-User + - SSO-User +---- + +. Set the optional parameters, as needed. ++ +[[reqhead-ww-auth-optional]] +.Optional parameters +==== +---- +oauthConfig: + ... + identityProviders: + - name: my_request_header_provider + challenge: true + login: true + mappingMethod: claim + provider: + apiVersion: v1 + kind: RequestHeaderIdentityProvider + challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" + loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" + clientCA: /path/to/client-ca.file <1> + clientCommonNames: <2> + - my-auth-proxy + headers: <3> + - X-Remote-User + - SSO-User + emailHeaders: <4> + - X-Remote-User-Email + nameHeaders: <5> + - X-Remote-User-Display-Name + preferredUsernameHeaders: <6> + - X-Remote-User-Login +---- +<1> 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. +<2> 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`. +<3> Optional: Header names to check, in order, for an email address. The first header containing +a value is used as the email address. This parameter is case-insensitive. +<4> Optional: Header names to check, in order, for a display name. The first header containing +a value is used as the display name. This parameter is case-insensitive. +<5> Optional: 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. This parameter is case-insensitive. +==== + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + +. xref:RequestHeaderIdentityProviderProxy[Configure the Authentication Proxy]. + + +[[redirect-browser-based-requests]] +=== Configuring for Browser-Based Requests + +To redirect unauthenticated requests from clients expecting browser-based login flows: + +. Edit the master configuration file using the xref:reqhead-ww-auth-optional[example below]. ++ +---- +/etc/origin/master/master-config.yaml +---- ++ +. Set the `login` parameter to `true`. ++ +---- +oauthConfig: + ... + identityProviders: + - challenge: + login: true +---- ++ +`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. + +. Specify the `mappingMethod` parameter to determine how identities are mapped to users. +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=configuring_authentication_common_steps2] + +. Set the `name` parameter to an appropriate string. This provider name is prefixed to provider user names to form an identity name. ++ +---- +name: my_request_header_provider +---- + +. Set the `provider.loginURL` parameter to the authenticating proxy URL that +will authenticate interactive clients and then proxy the request to `\https:///oauth/authorize`. ++ +The `provider.loginURL` parameter can include +the following tokens in the query portion of the URL: ++ +include::install_config/authentication/configuring_authentication_request_header.adoc[tag=IDP-urlquerytokens] ++ +[[reqhead-auth-example-config]] +.Master Configuration Using `RequestHeaderIdentityProvider` +==== + +---- +oauthConfig: + ... + identityProviders: + - challenge: true + login: true + mappingMethod: claim + name: my_request_header_provider + provider: + apiVersion: v1 + kind: RequestHeaderIdentityProvider + challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" + loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" <3> +---- +<1> Specify *_RequestHeaderIdentityProvider_* as the provider kind. +<2> 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. +==== + +. Set the optional parameters, as xref:reqhead-ww-auth-optional[described in the previous section]. + +include::install_config/authentication/configuring_authentication_allow_all.adoc[tag=restart-after-config-master] + +. xref:RequestHeaderIdentityProviderProxy[Configure the Authentication Proxy]. + + +[[RequestHeaderIdentityProviderProxy]] +== Configuring the Apache Authentication Proxy + +//// +This is similar to how +link:https://access.redhat.com/documentation/en-US/OpenShift_Enterprise/2/html/Deployment_Guide/Configuring_OpenShift_Enterprise_Authentication.html[the remote user plug-in in OpenShift Enterprise 2] allowed administrators to +provide Kerberos, LDAP, and many other forms of enterprise authentication. +//// + +When using `RequestHeaderIdentityProvider`, users must access +`\https:///oauth/authorize` (and subpaths) through 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`. + +This example configures an authentication proxy on the same host as the master. +Having the proxy and master is one option and might not +be suitable for your environment. For example, if you were already +xref:../../install_config/router/index.adoc#install-config-router-overview[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_form`, it is not required and other proxies can be used if the following requirements are met: + +* Block the `X-Remote-User` header from client requests to prevent spoofing. +* Enforce client certificate authentication in the `RequestHeaderIdentityProvider` configuration. +* Require the `X-Csrf-Token` header be set for all authentication request using the challenge flow. +* 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. +* 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?...` +* 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?...` + + +=== Installing the Prerequisites + +Perform the following tasks: + +. The `mod_auth_form` module is shipped as part of the `mod_session` package that +is found in the link:https://access.redhat.com/solutions/392003[Optional channel]. ++ +---- +# yum install -y httpd mod_ssl mod_session apr-util-openssl +---- + +. Generate a CA for validating requests that submit the trusted header. This CA +should be used as the file name for `clientCA` in the +xref:requestheader-master-ca-config[master's identity provider configuration]. ++ +---- +# oadm 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 `oadm 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. + +. Generate a client certificate for the proxy. This can be done using any x509 +certificate tooling. For convenience, the `oadm` CLI can be used: ++ +---- +# oadm 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 `oadm ca create-server-cert` command can be used. ++ +[NOTE] +The `oadm 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. + + +=== 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. + +Configure Apache using the following example: + +---- +LoadModule auth_form_module modules/mod_auth_form.so +LoadModule session_module modules/mod_session.so +LoadModule request_module modules/mod_request.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 + AuthType basic + + + + # Insert your backend server name/ip here. + ProxyPass https://[MASTER]:8443/oauth/authorize + + # mod_auth_form providers are implemented by mod_authn_dbm, mod_authn_file, + # mod_authn_dbd, mod_authnz_ldap and mod_authn_socache. + AuthFormProvider file + AuthType form + AuthName openshift + ErrorDocument 401 /login.html + + + + AuthUserFile /etc/origin/master/htpasswd + AuthName openshift + Require valid-user + RequestHeader set X-Remote-User %{REMOTE_USER}s env=REMOTE_USER + + # 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_form usage and replace it with + # something like mod_auth_kerb, mod_auth_gsspai or even mod_auth_mellon. + # The former would be able to support both the login and challenge flows + # from the Master. Mellon would likely only support the login flow. + + # For Kerberos + # yum install mod_auth_gssapi + # AuthType GSSAPI + # GssapiCredStore keytab:/etc/httpd.keytab + + + + +RequestHeader unset X-Remote-User +---- + + +=== Additional mod_auth_form Requirements + +A sample login page is available from the +link:https://github.com/openshift/openshift-extras/tree/master/misc/form_auth[openshift_extras] +repository. This file should be placed in the `DocumentRoot` location +(*_/var/www/html_* by default). + +. Create the users in the system Apache is using to store +accounts information. In this example, file-backed authentication is used: ++ +---- +# yum -y install httpd-tools +# touch /etc/origin/master/htpasswd +# htpasswd /etc/origin/master/htpasswd +---- + +. Update the `identityProviders` stanza in the +*_/etc/origin/master/master-config.yaml_* file: ++ +[[requestheader-master-ca-config]] +---- + 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 +---- + +. Restart the following services: ++ +---- +# systemctl restart httpd +ifdef::openshift-origin[] +# systemctl restart origin-master +endif::[] +ifdef::openshift-enterprise[] +# systemctl restart atomic-openshift-master +endif::[] +---- + + +== Verifying the Configuration + +To verify the Apache 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: ++ +---- +# curl -k -v -H 'X-Csrf-Token: 1' \ + '' +---- + +. This should show a redirect with an access token: ++ +---- +# curl -k -v -u : \ + -H 'X-Csrf-Token: 1' '' +---- diff --git a/install_config/authentication/index.adoc b/install_config/authentication/index.adoc new file mode 100644 index 000000000000..0b14a9701891 --- /dev/null +++ b/install_config/authentication/index.adoc @@ -0,0 +1,24 @@ +[[install-config-configuring-authentication-index]] += Overview +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: + +toc::[] +{nbsp} + + +The {product-title} +xref:../../architecture/infrastructure_components/kubernetes_infrastructure.adoc#master[master] +includes a built-in +xref:../../architecture/additional_concepts/authentication.adoc#oauth[OAuth +server]. Developers and administrators obtain +xref:../../architecture/additional_concepts/authentication.adoc#api-authentication[OAuth +access tokens] to authenticate themselves to the API. + +As an administrator, you can configure the specific OAuth identity provider to use for user access and can use built-in user agents to protect the API. + +* xref:../../install_config/authentication/configuring_authentication_identity_provider.adoc#install-config-configuring-authentication-providers[Configuring OAuth Identity Providers] + +* xref:../../install_config/authentication/configuring_authentication_user_agent.adoc#configuring-authentication-user-agent-api[Configuring User Agents to Prevent Access to the APIs]. diff --git a/install_config/configuring_authentication_user_agent.adoc b/install_config/configuring_authentication_user_agent.adoc new file mode 100644 index 000000000000..161ef80f6e4a --- /dev/null +++ b/install_config/configuring_authentication_user_agent.adoc @@ -0,0 +1,100 @@ +[[configuring-authentication-user-agent-api]] += Configuring User Agents to Prevent Access to the APIs +{product-author} +{product-version} +:data-uri: +:icons: +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +toc::[] + +== Overview + +{product-title} implements a user agent that can be used to prevent an application developer's CLI accessing the {product-title} API. + + + +== Configuring User Agents + +User agents for the {product-title} CLI are constructed from a set of values +within {product-title}: + +---- +/ (/) / +---- + +For example: + +* If you have the following values: ++ +** `` = `oc` +** `` = The client version. For example, `v3.5.0`. Requests made against the Kubernetes +API at `/api` receive the Kubernetes version, while requests made against the +{product-title} API at `/oapi` receive the {product-title} version (as specified +by `oc version`) +** `` = `linux` +** `` = `amd64` +** `` = `openshift`, or `kubernetes` depending on if the request is made against the Kubernetes API at `/api`, or the {product-title} API at `/oapi` +** `` = The Git commit of the client version (for example, `f034127`) + +* The user agent will be: ++ +---- +oc/v3.5.0 (linux/amd64) openshift/f034127 +---- + +As an {product-title} administrator, you can prevent clients from accessing the +API with the `userAgentMatching` configuration setting of a master +configuration. So, if a client is using a particular library or +binary, they will be prevented from accessing the API. + +The following user agent example denies the Kubernetes 1.2 client binary, +OpenShift Origin 1.1.3 binary, and the POST and PUT `httpVerbs`: + +==== +---- +policyConfig: + userAgentMatchingConfig: + defaultRejectionMessage: "Your client is too old. Go to https://example.org to update it." + deniedClients: + - regex: '\w+/v(?:(?:1\.1\.1)|(?:1\.0\.1)) \(.+/.+\) openshift/\w{7}' + - regex: '\w+/v(?:1\.1\.3) \(.+/.+\) openshift/\w{7}' + httpVerbs: + - POS5 + - PUT + - regex: '\w+/v1\.2\.0 \(.+/.+\) kubernetes/\w{7}' + httpVerbs: + - POST + - PUT + requiredClients: null +---- +==== + +Administrators can also deny clients that do not exactly match the expected +clients: + +==== +---- +policyConfig: + userAgentMatchingConfig: + defaultRejectionMessage: "Your client is too old. Go to https://example.org to update it." + deniedClients: [] + requiredClients: + - regex: '\w+/v1\.1\.3 \(.+/.+\) openshift/\w{7}' + - regex: '\w+/v1\.2\.0 \(.+/.+\) kubernetes/\w{7}' + httpVerbs: + - POST + - PUT +---- +==== + +[NOTE] +==== +When the client's user agent mismatches the configuration, errors occur. To +ensure that mutating requests match, enforce a whitelist. Rules are mapped to +specific verbs, so you can ban mutating requests while allowing non-mutating +requests. +==== diff --git a/install_config/install/advanced_install.adoc b/install_config/install/advanced_install.adoc index 4eca18a6b658..377d7317c021 100644 --- a/install_config/install/advanced_install.adoc +++ b/install_config/install/advanced_install.adoc @@ -37,6 +37,7 @@ xref:running-the-advanced-installation-system-container[containerized version of Technology Preview feature. ==== + ifdef::openshift-enterprise[] Alternatively, you can use the xref:../../install_config/install/quick_install.adoc#install-config-install-quick-install[quick installation] method if you prefer an interactive installation experience. @@ -213,9 +214,9 @@ use the multitenant plug-in. |`openshift_master_identity_providers` |This variable overrides the -xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[identity provider], which +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[identity provider], which defaults to -xref:../../install_config/configuring_authentication.adoc#DenyAllPasswordIdentityProvider[Deny +xref:../../install_config/authentication/configuring_authentication_deny_all.adoc#install-config-configuring-authentication-deny[Deny All]. |`openshift_master_named_certificates` @@ -244,7 +245,7 @@ validity for etcd CA, peer, server and client certificates. Defaults to `1825` |`openshift_master_session_name` .4+.^|These variables override defaults for -xref:../../install_config/configuring_authentication.adoc#session-options[session +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[session options] in the OAuth configuration. See xref:advanced-install-session-options[Configuring Session Options] for more information. |`openshift_master_session_max_seconds` @@ -449,6 +450,7 @@ meaning that it is available for placement of new pods. See xref:marking-masters-as-unschedulable-nodes[Configuring Schedulability on Masters]. |=== +<<<<<<< HEAD [[configuring-host-port]] === Configuring Master API and Console Ports @@ -474,6 +476,8 @@ For example: openshift_master_api_port=3443 openshift_master_console_port=8756 ---- +======= +>>>>>>> Edits to the Configuring Authentication and User Agent page [[configuring-cluster-pre-install-checks]] === Configuring Cluster Pre-install Checks @@ -697,6 +701,75 @@ inventory file in the `[OSEv3:vars]` section: openshift_use_etcd_system_container=True ---- +[[advanced-install-configuring-oauth]] +=== Configuring OAuth Providers + +The {product-title} xref:../../architecture/infrastructure_components/kubernetes_infrastructure.adoc#master[master] +includes a built-in +xref:../../architecture/additional_concepts/authentication.adoc#oauth[OAuth +server]. Developers and administrators obtain +xref:../../architecture/additional_concepts/authentication.adoc#api-authentication[OAuth +access tokens] to authenticate themselves to the API. + +You can configure OAuth using the +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[master configuration file to specify an +identity provider]. +Alternatively, you can do this after the installation using the master configuration file. + +When you install {product-title} using the Advanced Installation +method, the +ifdef::openshift-enterprise[] +xref:../../install_config/authentication/configuring_authentication_deny_all.adoc#install-config-configuring-authentication-deny[Deny All] identity provider is +used by default, which denies access for all user names and +passwords. To allow access, you must choose a different identity provider and +configure the master configuration file appropriately (located at +*_/etc/origin/master/master-config.yaml_* by default). +endif::[] +ifdef::openshift-origin[] +xref:../../install_config/authentication/configuring_authentication_allow_all.adoc#install-config-configuring-authentication-allow[Allow All] identity provider is +used by default, which allows access for all user names and +passwords. +endif::[] + +[NOTE] +==== +xref:../architecture/additional_concepts/authorization.adoc#roles[Roles] need +to be assigned to administer the setup with an external user. +==== + +The Deny All default identity provider can be overridden during installation by configuring the `*openshift_master_identity_providers*` parameter in the inventory file. +xref:../../install_config/install/advanced_install.adoc#advanced-install-session-options[Session options in the OAuth configuration] are also configurable in the inventory file. + +.Example Identity Provider Configuration with Ansible +==== + +---- +# htpasswd auth +openshift_master_identity_providers=[{'name': 'htpasswd_auth', 'login': 'true', 'challenge': 'true', 'kind': 'HTPasswdPasswordIdentityProvider', 'filename': '/etc/origin/master/htpasswd'}] +# Defining htpasswd users +#openshift_master_htpasswd_users={'user1': '', 'user2': '' +# or +#openshift_master_htpasswd_file= + +# Allow all auth +#openshift_master_identity_providers=[{'name': 'allow_all', 'login': 'true', 'challenge': 'true', 'kind': 'AllowAllPasswordIdentityProvider'}] + +# LDAP auth +#openshift_master_identity_providers=[{'name': 'my_ldap_provider', 'challenge': 'true', 'login': 'true', 'kind': 'LDAPPasswordIdentityProvider', 'attributes': {'id': ['dn'], 'email': ['mail'], 'name': ['cn'], 'preferredUsername': ['uid']}, 'bindDN': '', 'bindPassword': '', 'ca': '', 'insecure': 'false', 'url': 'ldap://ldap.example.com:389/ou=users,dc=example,dc=com?uid'}] +# Configuring the ldap ca certificate +#openshift_master_ldap_ca= +# or +#openshift_master_ldap_ca_file= + +# Available variables for configuring certificates for other identity providers: +#openshift_master_openid_ca +#openshift_master_openid_ca_file +#openshift_master_request_header_ca +#openshift_master_request_header_ca_file +---- +==== + + [[advanced-install-configuring-registry-location]] === Configuring a Registry Location @@ -1295,7 +1368,7 @@ master.example.com openshift_node_labels="{'region': 'infra','zone': 'default'}" [[advanced-install-session-options]] === Configuring Session Options -xref:../../install_config/configuring_authentication.adoc#session-options[Session +xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[Session options] in the OAuth configuration are configurable in the inventory file. By default, Ansible populates a `*sessionSecretsFile*` with generated authentication and encryption secrets so that sessions generated by one master @@ -1328,6 +1401,7 @@ must be 16, 24, or 32 characters long, to select AES-128, AES-192, or AES-256: openshift_master_session_encryption_secrets=['DONT+USE+THIS+SECRET+b4NV+pmZNSO'] ---- + [[advanced-install-custom-certificates]] === Configuring Custom Certificates @@ -2691,14 +2765,14 @@ xref:uninstalling-advanced[Uninstalling {product-title}] for instructions. Now that you have a working {product-title} instance, you can: -- xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[Configure +- xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[Configure authentication]; by default, authentication is set to ifdef::openshift-enterprise[] -xref:../../install_config/configuring_authentication.adoc#DenyAllPasswordIdentityProvider[Deny +xref:../../install_config/authentication/configuring_authentication_deny_all.adoc#install-config-configuring-authentication-deny[Deny All]. endif::[] ifdef::openshift-origin[] -xref:../../install_config/configuring_authentication.adoc#AllowAllPasswordIdentityProvider[Allow +xref:../../install_config/authentication/configuring_authentication_allow_all.adoc#install-config-configuring-authentication-allow[Allow All]. endif::[] - Deploy an xref:../../install_config/registry/index.adoc#install-config-registry-overview[integrated Docker registry]. diff --git a/install_config/install/quick_install.adoc b/install_config/install/quick_install.adoc index 8e9bd1222f58..05d2b8cf7c85 100644 --- a/install_config/install/quick_install.adoc +++ b/install_config/install/quick_install.adoc @@ -369,9 +369,9 @@ installation method] for more options. Now that you have a working {product-title} instance, you can: -- xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[Configure +- xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[Configure authentication]; by default, authentication is set to -xref:../../install_config/configuring_authentication.adoc#DenyAllPasswordIdentityProvider[Deny +xref:../../install_config/authentication/configuring_authentication_deny_all.adoc#install-config-configuring-authentication-deny[Deny All]. - Configure the automatically-deployed xref:../../install_config/registry/index.adoc#install-config-registry-overview[integrated Docker registry]. - Configure the automatically-deployed xref:../../install_config/router/index.adoc#install-config-router-overview[router]. diff --git a/install_config/install/stand_alone_registry.adoc b/install_config/install/stand_alone_registry.adoc index f090b603f1c0..313706a1452e 100644 --- a/install_config/install/stand_alone_registry.adoc +++ b/install_config/install/stand_alone_registry.adoc @@ -39,7 +39,7 @@ OCR provides the following capabilities: - A user-focused xref:../../install_config/registry/deploy_registry_existing_clusters.adoc#registry-console[registry web console]. - xref:../../install_config/registry/securing_and_exposing_registry.adoc#install-config-registry-securing-exposing[Secured traffic] by default, served via TLS. -- Global xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[identity provider authentication]. +- Global xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[identity provider authentication]. - A xref:../../architecture/core_concepts/projects_and_users.adoc#architecture-core-concepts-projects-and-users[project namespace] model to enable teams to collaborate through xref:../../architecture/additional_concepts/authorization.adoc#architecture-additional-concepts-authorization[role-based access control (RBAC)] authorization. diff --git a/install_config/master_node_configuration.adoc b/install_config/master_node_configuration.adoc index 527db2c01c5b..7e519bb51933 100644 --- a/install_config/master_node_configuration.adoc +++ b/install_config/master_node_configuration.adoc @@ -1071,7 +1071,7 @@ kubeletArguments: [[master-node-configuration-passwords-and-other-data]] == Passwords and Other Sensitive Data -For some xref:configuring_authentication.adoc#install-config-configuring-authentication[authentication configurations], +For some xref:../install_config/authentication/index.adoc#install-config-configuring-authentication-index[authentication configurations], an LDAP `bindPassword` or OAuth `clientSecret` value is required. Instead of specifying these values directly in the master configuration file, these values may be provided as environment variables, external files, diff --git a/install_config/registry/accessing_registry.adoc b/install_config/registry/accessing_registry.adoc index 1588d9b77eb7..24099ffffcf0 100644 --- a/install_config/registry/accessing_registry.adoc +++ b/install_config/registry/accessing_registry.adoc @@ -132,7 +132,7 @@ following, depending on your intended usage: - For any direct access, you must have a xref:../../architecture/core_concepts/projects_and_users.adoc#users[regular user], if one does not already exist, for your -preferred xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[identity +preferred xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[identity provider]. A regular user can generate an access token required for logging in to the registry. xref:../../architecture/core_concepts/projects_and_users.adoc#users[System diff --git a/install_config/web_console_customization.adoc b/install_config/web_console_customization.adoc index 915e9755b1fe..0cf2adca332a 100644 --- a/install_config/web_console_customization.adoc +++ b/install_config/web_console_customization.adoc @@ -1042,7 +1042,7 @@ Relative paths are resolved relative to the master configuration file. You must restart the server after changing this configuration. When there are multiple login providers configured or when the -xref:../install_config/configuring_authentication.adoc#identity-providers[`alwaysShowProviderSelection`] +xref:../install_config/authentication/index.adoc#install-config-configuring-authentication-index[`alwaysShowProviderSelection`] option in the *_master-config.yaml_* file is set to *true*, each time a user's token to {product-title} expires, the user is presented with this custom page before they can proceed with other tasks. @@ -1100,9 +1100,9 @@ assetConfig: ---- This can be useful when authenticating with -xref:../install_config/configuring_authentication.adoc#RequestHeaderIdentityProvider[Request +xref:../install_config/authentication/configuring_authentication_request_header.adoc#install-config-configuring-authentication-request[Request Header] and OAuth or -xref:../install_config/configuring_authentication.adoc#OpenID[OpenID] identity +xref:../install_config/authentication/configuring_authentication_openid.adoc#install-config-configuring-authentication-openid[OpenID] identity providers, which require visiting an external URL to destroy single sign-on sessions. diff --git a/registry_quickstart/administrators/system_configuration.adoc b/registry_quickstart/administrators/system_configuration.adoc index 501026bf461d..e42309037288 100644 --- a/registry_quickstart/administrators/system_configuration.adoc +++ b/registry_quickstart/administrators/system_configuration.adoc @@ -63,7 +63,7 @@ $ sudo systemctl restart atomic-registry-master.service Global configuration items managed by this configuration file include: -* xref:../../install_config/configuring_authentication.adoc#install-config-configuring-authentication[Configure authentication] +* xref:../../install_config/authentication/index.adoc#install-config-configuring-authentication-index[Configure authentication] by integrating with an identity provider * Manage xref:../../admin_guide/managing_projects.adoc#admin-guide-managing-projects[project namespace self-provisioning]