"Fossies" - the Fresh Open Source Software Archive

Member "keystone-17.0.0/doc/source/admin/federation/openidc.inc" (13 May 2020, 8872 Bytes) of package /linux/misc/openstack/keystone-17.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) fasm source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "openidc.inc" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 16.0.1_vs_17.0.0.

    1 .. -*- rst -*-
    2 
    3 ..
    4       Licensed under the Apache License, Version 2.0 (the "License"); you may
    5       not use this file except in compliance with the License. You may obtain
    6       a copy of the License at
    7 
    8       http://www.apache.org/licenses/LICENSE-2.0
    9 
   10       Unless required by applicable law or agreed to in writing, software
   11       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   12       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   13       License for the specific language governing permissions and limitations
   14       under the License.
   15 
   16 .. _federation_openidc:
   17 
   18 -------------------------
   19 Setting Up OpenID Connect
   20 -------------------------
   21 
   22 See :ref:`keystone-as-sp` before proceeding with these OpenIDC-specific
   23 instructions.
   24 
   25 These examples use Google as an OpenID Connect Identity Provider. The Service
   26 Provider must be added to the Identity Provider in the `Google API console`_.
   27 
   28 .. _Google API console: https://console.developers.google.com/
   29 
   30 Configuring Apache HTTPD for mod_auth_openidc
   31 ---------------------------------------------
   32 
   33 .. note::
   34 
   35    You are advised to carefully examine the `mod_auth_openidc documentation`_.
   36 
   37 .. _mod_auth_openidc documentation: https://github.com/zmartzone/mod_auth_openidc#how-to-use-it
   38 
   39 Install the Module
   40 ~~~~~~~~~~~~~~~~~~
   41 
   42 Install the Apache module package. For example, on Ubuntu:
   43 
   44 .. code-block:: console
   45 
   46    # apt-get install libapache2-mod-auth-openidc
   47 
   48 The package and module name will differ between distributions.
   49 
   50 Configure mod_auth_openidc
   51 ~~~~~~~~~~~~~~~~~~~~~~~~~~
   52 
   53 In the Apache configuration for the keystone VirtualHost, set the following OIDC
   54 options:
   55 
   56 .. code-block:: apache
   57 
   58    OIDCClaimPrefix "OIDC-"
   59    OIDCResponseType "id_token"
   60    OIDCScope "openid email profile"
   61    OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration
   62    OIDCOAuthVerifyJwksUri https://www.googleapis.com/oauth2/v3/certs
   63    OIDCClientID <openid_client_id>
   64    OIDCClientSecret <openid_client_secret>
   65    OIDCCryptoPassphrase <random string>
   66    OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth
   67 
   68 ``OIDCScope`` is the list of attributes that the user will authorize the
   69 Identity Provider to send to the Service Provider. ``OIDCClientID`` and
   70 ``OIDCClientSecret`` must be generated and obtained from the Identity Provider.
   71 ``OIDCProviderMetadataURL`` is a URL from which the Service Provider will fetch
   72 the Identity Provider's metadata. ``OIDCOAuthVerifyJwksUri`` is a URL from
   73 which the Service Provider will download the public key from the Identity
   74 Provider to check if the user's access token is valid or not, this configuration
   75 must be used while using the AuthType ``auth-openidc``, when using the AuthType
   76 ``openid-connect`` and the OIDCProviderMetadataURL is configured, this property
   77 will not be necessary.
   78 ``OIDCRedirectURI`` is a vanity URL that must
   79 point to a protected path that does not have any content, such as an extension
   80 of the protected federated auth path.
   81 
   82 .. note::
   83 
   84    If using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` must
   85    be specified to have only alphanumerics or a dash ("-"). This is because
   86    `mod_wsgi blocks headers that do not fit this criteria`_.
   87 
   88 .. _mod_wsgi blocks headers that do not fit this criteria: http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed
   89 
   90 Configure Protected Endpoints
   91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   92 
   93 Configure each protected path to use the ``openid-connect`` AuthType:
   94 
   95 .. code-block:: apache
   96 
   97    <Location /v3/OS-FEDERATION/identity_providers/google/protocols/openid/auth>
   98        Require valid-user
   99        AuthType openid-connect
  100    </Location>
  101 
  102 .. note::
  103   To add support to Bearer Access Token authentication flow that is used by
  104   applications that do not adopt the browser flow, such the OpenStack CLI, you
  105   will need to change the AuthType from ``openid-connect`` to
  106   ``auth-openidc``.
  107 
  108 Do the same for the WebSSO auth paths if using horizon:
  109 
  110 .. code-block:: apache
  111 
  112    <Location /v3/auth/OS-FEDERATION/websso/openid>
  113        Require valid-user
  114        AuthType openid-connect
  115    </Location>
  116    <Location /v3/auth/OS-FEDERATION/identity_providers/google/protocols/openid/websso>
  117        Require valid-user
  118        AuthType openid-connect
  119    </Location>
  120 
  121 Remember to reload Apache after altering the VirtualHost:
  122 
  123 .. code-block:: console
  124 
  125    # systemctl reload apache2
  126 
  127 .. note::
  128 
  129    When creating :ref:`mapping rules <create_a_mapping>`, in keystone, note that the 'remote'
  130    attributes will be prefixed, with ``HTTP_``, so for instance, if you set
  131    ``OIDCClaimPrefix`` to ``OIDC-``, then a typical remote value to check for
  132    is: ``HTTP_OIDC_ISS``.
  133 
  134 Configuring Multiple Identity Providers
  135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  136 
  137 To configure multiples Identity Providers in your environment you will need to
  138 set your OIDC options like the following options:
  139 
  140 .. code-block:: apache
  141 
  142     OIDCClaimPrefix "OIDC-"
  143     OIDCResponseType "id_token"
  144     OIDCScope "openid email profile"
  145     OIDCMetadataDir <IDP metadata directory>
  146     OIDCCryptoPassphrase <random string>
  147     OIDCRedirectURI https://sp.keystone.example.org/redirect_uri
  148     OIDCOAuthVerifyCertFiles <kid>#</path/to-cert.pem> <kid2>#</path/to-cert2.pem> <kidN>#</path/to-certN.pem>
  149 
  150 The ``OIDCOAuthVerifyCertFiles`` is a tuple separated with `space`
  151 containing the key-id (kid) of the Issuer's public key and a path to
  152 the Issuer certificate. The separator ``#`` is used to split the (``kid``)
  153 and the public certificate address
  154 
  155 The metadata folder configured in the option ``OIDCMetadataDir`` must have all
  156 your Identity Providers configurations, the name of the files will be
  157 the name (with path) of the Issuers like:
  158 
  159 .. code-block::
  160 
  161     - <IDP metadata directory>
  162       |
  163       - accounts.google.com.client
  164       |
  165       - accounts.google.com.conf
  166       |
  167       - accounts.google.com.provider
  168       |
  169       - keycloak.example.org%2Fauth%2Frealms%2Fidp.client
  170       |
  171       - keycloak.example.org%2Fauth%2Frealms%2Fidp.conf
  172       |
  173       - keycloak.example.org%2Fauth%2Frealms%2Fidp.provider
  174 
  175 .. note::
  176   The name of the file must be url-encoded if needed, as the Apache2 mod_auth_openidc
  177   will get the raw value from the query parameter ``iss`` from the http request
  178   and check if there is a metadata with this name, as the query parameter is
  179   url-encoded, so the metadata file name need to be encoded too. For example, if you have an
  180   Issuer with ``/`` in the URL, then you need to escape it to ``%2F`` by
  181   applying a URL escape in the file name.
  182 
  183 The content of these files must be a JSON like
  184 
  185 ``accounts.google.com.client``:
  186 
  187 .. code-block:: json
  188 
  189     {
  190       "client_id":"<openid_client_id>",
  191       "client_secret":"<openid_client_secret>"
  192     }
  193 
  194 The ``.client`` file handles the SP credentials in the Issuer.
  195 
  196 ``accounts.google.com.conf``:
  197 
  198 This file will be a JSON that overrides some of OIDC options. The options
  199 that are able to be overridden are listed in the
  200 `OpenID Connect Apache2 plugin documentation`_.
  201 
  202 .. _`OpenID Connect Apache2 plugin documentation`: https://github.com/zmartzone/mod_auth_openidc/wiki/Multiple-Providers#opclient-configuration
  203 
  204 If you do not want to override the config values, you can leave this file as
  205 an empty JSON like ``{}``.
  206 
  207 ``accounts.google.com.provider``:
  208 
  209 This file will contain all specifications about the IdentityProvider. To
  210 simplify, you can just use the JSON returned in the ``.well-known`` endpoint:
  211 
  212 .. code-block:: json
  213 
  214   {
  215     "issuer": "https://accounts.google.com",
  216     "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  217     "token_endpoint": "https://oauth2.googleapis.com/token",
  218     "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  219     "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  220     "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  221     "response_types_supported": [
  222      "code",
  223      "token",
  224      "id_token",
  225      "code token",
  226      "code id_token",
  227      "token id_token",
  228      "code token id_token",
  229      "none"
  230     ],
  231     "subject_types_supported": [
  232      "public"
  233     ],
  234     "id_token_signing_alg_values_supported": [
  235      "RS256"
  236     ],
  237     "scopes_supported": [
  238      "openid",
  239      "email",
  240      "profile"
  241     ],
  242     "token_endpoint_auth_methods_supported": [
  243      "client_secret_post",
  244      "client_secret_basic"
  245     ],
  246     "claims_supported": [
  247      "aud",
  248      "email",
  249      "email_verified",
  250      "exp",
  251      "family_name",
  252      "given_name",
  253      "iat",
  254      "iss",
  255      "locale",
  256      "name",
  257      "picture",
  258      "sub"
  259     ],
  260     "code_challenge_methods_supported": [
  261      "plain",
  262      "S256"
  263     ]
  264   }
  265 
  266 Continue configuring keystone
  267 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  268 
  269 :ref:`Continue configuring keystone <federation_configuring_keystone>`