Keystone’s one-stop-shop for all federated identity documentation.
Note
This feature is considered stable and supported as of the Juno release.
This approach to federation supports keystone as a Service Provider, consuming identity properties issued by an external Identity Provider, such as SAML assertions or OpenID Connect claims.
Federated users are not mirrored in the keystone identity backend (for example, using the SQL driver). The external Identity Provider is responsible for authenticating users, and communicates the result of authentication to keystone using identity properties. Keystone maps these values to keystone user groups and assignments created in keystone.
The following configuration steps were performed on a machine running Ubuntu 12.04 and Apache 2.2.22.
To enable federation, you’ll need to:
There is currently support for two major federation protocols:
Now that the Identity Provider and keystone are communicating we can start to configure federation.
Note
saml2 has been deprecated as of the Mitaka release. Support for the saml2 wrapper will be removed as of the “O” release. The recommended authentication method is mapped, which supports saml2.
Add the authentication methods to the [auth] section in keystone.conf. Names should be equal to protocol names added via Identity API v3. Here we use examples mapped and openid.
[auth]
methods = external,password,token,mapped,openid
As mentioned earlier, no new users will be added to the Identity backend, but the Identity Service requires group-based role assignments to authorize federated users. The federation mapping function will map the user into local Identity Service groups objects, and hence to local role assignments.
Thus, it is required to create the necessary Identity Service groups that correspond to the Identity Provider’s groups; additionally, these groups should be assigned roles on one or more projects or domains.
You may be interested in more information on group management and role assignments, both of which are exposed to the CLI via python-openstackclient.
To utilize federation the following must be created in the Identity Service:
Read more about federation in keystone.
Create an Identity Provider object in keystone, which represents the Identity Provider we will use to authenticate end users.
Read more about identity providers.
A mapping is a list of rules. The only Identity API objects that will support mapping are groups and users.
Mapping adds a set of rules to map federation protocol attributes to Identity API objects. There are many different ways to setup as well as combine these rules. More information on rules can be found on the Mapping Combinations page.
An Identity Provider has exactly one mapping specified per protocol. Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol.
Read more about mapping.
A protocol contains information that dictates which Mapping rules to use for an incoming request made by an IdP. An IdP may have multiple supported protocols.
Add Protocol object and specify the mapping id you want to use with the combination of the IdP and Protocol.
Unlike other authentication methods in the Identity Service, the user does not issue an HTTP POST request with authentication data in the request body. To start federated authentication a user must access the dedicated URL with Identity Provider’s and Protocol’s identifiers stored within a protected URL. The URL has a format of: /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth.
In this instance we follow a standard SAML2 authentication procedure, that is, the user will be redirected to the Identity Provider’s authentication webpage and be prompted for credentials. After successfully authenticating the user will be redirected to the Service Provider’s endpoint. If using a web browser, a token will be returned in XML format.
In the returned unscoped token, a list of Identity Service groups the user belongs to will be included.
Read more about getting an unscoped token.
Note that the request does not include a body. The following url would be considered protected by mod_shib and Apache, as such a request made to the URL would be redirected to the Identity Provider, to start the SAML authentication procedure.
$ curl -X GET -D - http://localhost:5000/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth
By using the previously returned token, the user can issue requests to the list projects and domains that are accessible.
Read more about listing resources.
$ curl -X GET -H "X-Auth-Token: <unscoped token>" http://localhost:5000/v3/OS-FEDERATION/projects
or
$ curl -X GET -H "X-Auth-Token: <unscoped token>" http://localhost:5000/v3/OS-FEDERATION/domains
A federated user may request a scoped token, by using the unscoped token. A project or domain may be specified by either id or name. An id is sufficient to uniquely identify a project or domain.
Read more about getting a scoped token.
$ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["mapped"],"saml2":{"id":"<unscoped_token_id>"}},"scope":{"project":{"domain": {"name": "Default"},"name":"service"}}}}' -D - http://localhost:5000/v3/auth/tokens
Note
This feature is experimental and unsupported in Juno (with several issues that will not be backported). These issues have been fixed and this feature is considered stable and supported as of the Kilo release.
Note
This feature requires installation of the xmlsec1 tool via your distribution packaging system (for instance apt or yum)
Example for apt:
$ apt-get install xmlsec1
There are certain settings in keystone.conf that must be setup, prior to attempting to federate multiple keystone deployments.
Within keystone.conf, assign values to the [saml] related fields, for example:
[saml]
certfile=/etc/keystone/ssl/certs/ca.pem
keyfile=/etc/keystone/ssl/private/cakey.pem
idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
Though not necessary, the follow Organization configuration options should also be setup. It is recommended that these values be URL safe.
idp_organization_name=example_company
idp_organization_display_name=Example Corp.
idp_organization_url=example.com
As with the Organization options, the Contact options, are not necessary, but it’s advisable to set these values too.
idp_contact_company=example_company
idp_contact_name=John
idp_contact_surname=Smith
idp_contact_email=jsmith@example.com
idp_contact_telephone=555-55-5555
idp_contact_type=technical
In order to create a trust between the IdP and SP, metadata must be exchanged. To create metadata for your keystone IdP, run the keystone-manage command and pipe the output to a file. For example:
$ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
Note
The file location should match the value of the configuration option idp_metadata_path that was assigned in the previous section.
In this example we are creating a new Service Provider with an ID of BETA, a sp_url of http://beta.example.com/Shibboleth.sso/SAML2/ECP and a auth_url of http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth . The sp_url will be used when creating a SAML assertion for BETA and signed by the current keystone IdP. The auth_url is used to retrieve the token for BETA once the SAML assertion is sent. Although the enabled field is optional we are passing it set to true otherwise it will be set to false by default.
$ curl -s -X PUT \
-H "X-Auth-Token: $OS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"service_provider": {"auth_url": "http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth", "sp_url": "https://example.com:5000/Shibboleth.sso/SAML2/ECP", "enabled": true}}' \
http://localhost:5000/v3/OS-FEDERATION/service_providers/BETA | python -mjson.tool
Lastly, if a scoped token and a Service Provider scope are presented to the local keystone, the result will be a full ECP wrapped SAML Assertion, specifically intended for the Service Provider keystone.
Note
ECP stands for Enhanced Client or Proxy, an extension from the SAML2 protocol used in non-browser interfaces, like in the following example with cURL.
$ curl -s -X POST \
-H "Content-Type: application/json" \
-d '{"auth": {"scope": {"service_provider": {"id": "BETA"}}, "identity": {"token": {"id": "d793d935b9c343f783955cf39ee7dc3c"}, "methods": ["token"]}}}' \
http://localhost:5000/v3/auth/OS-FEDERATION/saml2/ecp
Note
Use URL http://localhost:5000/v3/auth/OS-FEDERATION/saml2 to request for pure SAML Assertions.
At this point the ECP wrapped SAML Assertion can be sent to the Service Provider keystone using the provided auth_url in the X-Auth-Url header present in the response containing the Assertion, and a valid OpenStack token, issued by a Service Provider keystone, will be returned.
Mapping adds a set of rules to map federation attributes to Keystone users and/or groups. An Identity Provider has exactly one mapping specified per protocol.
Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol.
A rule hierarchy looks as follows:
{
"rules": [
{
"local": [
{
"<user> or <group>"
}
],
"remote": [
{
"<condition>"
}
]
}
]
}
The mapping engine can be tested before creating a federated setup. It can be tested with the keystone-manage mapping_engine command:
$ keystone-manage mapping_engine --rules <file> --input <file>
Mappings support 5 different types of conditions:
empty: The rule is matched to all claims containing the remote attribute type. This condition does not need to be specified.
any_one_of: The rule is matched only if any of the specified strings appear in the remote attribute type. Condition result is boolean, not the argument that is passed as input.
not_any_of: The rule is not matched if any of the specified strings appear in the remote attribute type. Condition result is boolean, not the argument that is passed as input.
blacklist: The rule allows all except a specified set of groups. Condition result is the argument(s) passed as input minus what was matched in the blacklist.
whitelist: The rules allows a specified set of groups. Condition result is the argument(s) passed as input and is/are also present in the whitelist.
Note
empty, blacklist and whitelist are the only conditions that can be used in direct mapping ({0}, {1}, etc.)
Multiple conditions can be combined to create a single rule.
The following are all examples of mapping rule types.
{
"rules": [
{
"local": [
{
"user": {
"name": "{0} {1}",
"email": "{2}"
},
"group": {
"name": "{3}",
"domain": {
"id": "0cd5e9"
}
}
}
],
"remote": [
{
"type": "FirstName"
},
{
"type": "LastName"
},
{
"type": "Email"
},
{
"type": "OIDC_GROUPS"
}
]
}
]
}
Note
The numbers in braces {} are indices, they map in order. For example:
- Mapping to user with the name matching the value in remote attribute FirstName
- Mapping to user with the name matching the value in remote attribute LastName
- Mapping to user with the email matching value in remote attribute Email
- Mapping to a group(s) with the name matching the value(s) in remote attribute OIDC_GROUPS
Groups can have multiple values. Each value must be separated by a ; Example: OIDC_GROUPS=developers;testers
In <other_condition> shown below, please supply one of the following: any_one_of, or not_any_of.
{
"rules": [
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"id": "0cd5e9"
}
}
],
"remote": [
{
"type": "UserName"
},
{
"type": "HTTP_OIDC_GROUPIDS",
"<other_condition>": [
"HTTP_OIDC_EMAIL"
]
}
]
}
]
}
In <other_condition> shown below, please supply one of the following: blacklist, or whitelist.
{
"rules": [
{
"local": [
{
"user": {
"name": "{0}"
}
},
{
"groups": "{1}",
"domain": {
"id": "0cd5e9"
}
}
],
"remote": [
{
"type": "UserName"
},
{
"type": "HTTP_OIDC_GROUPIDS",
"<other_condition>": [
"me@example.com"
]
}
]
}
]
}
Note
If the user id and name are not specified in the mapping, the server tries to directly map REMOTE_USER environment variable. If this variable is also unavailable the server returns an HTTP 401 Unauthorized error.
Group ids and names can be provided in the local section:
{
"local": [
{
"group": {
"id":"0cd5e9"
}
}
]
}
{
"local": [
{
"group": {
"name": "developer_group",
"domain": {
"id": "abc1234"
}
}
}
]
}
{
"local": [
{
"group": {
"name": "developer_group",
"domain": {
"name": "private_cloud"
}
}
}
]
}
If a mapping is valid you will receive the following output:
{
"group_ids": "[<group-ids>]",
"user":
{
"domain":
{
"id": "Federated" or "<local-domain-id>"
},
"type": "ephemeral" or "local",
"name": "<local-user-name>",
"id": "<local-user-id>"
},
"group_names":
[
{
"domain":
{
"name": "<domain-name>"
},
"name":
{
"name": "[<groups-names>]"
}
}
{
"domain":
{
"name": "<domain-name>"
},
"name":
{
"name": "[<groups-names>]"
}
}
]
}
The type parameter specifies the type of user being mapped. The 2 possible user types are local and ephemeral.``local`` is displayed if the user has a domain specified. The user is treated as existing in the backend, hence the server will fetch user details (id, name, roles, groups).``ephemeral`` is displayed for a user that does not exist in the backend.
The id parameter in the service domain specifies the domain a user belongs to. Federated will be displayed if no domain is specified in the local rule. User is deemed ephemeral and becomes a member of service domain named Federated. If the domain is specified the local domain’s id will be displayed. If the mapped user is local, mapping engine will discard further group assigning and return set of roles configured for the user.
Note
Domain Federated is a service domain - it cannot be listed, displayed, added or deleted. There is no need to perform any operation on it prior to federation configuration.
Regular expressions can be used in a mapping by specifying the regex key, and setting it to true.
{
"rules": [
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"id": "0cd5e9"
}
},
],
"remote": [
{
"type": "UserName"
},
{
"type": "HTTP_OIDC_GROUPIDS",
"any_one_of": [
".*@yeah.com$"
]
"regex": true
}
]
}
]
}
This allows any user with a claim containing a key with any value in HTTP_OIDC_GROUPIDS to be mapped to group with id 0cd5e9.
Combinations of mappings conditions can also be done.
empty, any_one_of, and not_any_of can all be used in the same rule, but cannot be repeated within the same condition. any_one_of and not_any_of are mutually exclusive within a condition’s scope. So are whitelist and blacklist.
{
"rules": [
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"id": "0cd5e9"
}
},
],
"remote": [
{
"type": "UserName"
},
{
"type": "cn=IBM_Canada_Lab",
"not_any_of": [
".*@naww.com$"
],
"regex": true
},
{
"type": "cn=IBM_USA_Lab",
"any_one_of": [
".*@yeah.com$"
]
"regex": true
}
]
}
]
}
As before group names and users can also be provided in the local section.
This allows any user with the following claim information to be mapped to group with id 0cd5e9.
{"UserName":"<any_name>@yeah.com"}
{"cn=IBM_USA_Lab":"<any_name>@yeah.com"}
{"cn=IBM_Canada_Lab":"<any_name>@yeah.com"}
The following claims will be mapped:
Multiple rules can also be utilized in a mapping.
{
"rules": [
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"name": "non-contractors",
"domain": {
"id": "abc1234"
}
}
}
],
"remote": [
{
"type": "UserName"
},
{
"type": "orgPersonType",
"not_any_of": [
"Contractor",
"SubContractor"
]
}
]
},
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"name": "contractors",
"domain": {
"id": "abc1234"
}
}
}
],
"remote": [
{
"type": "UserName"
},
{
"type": "orgPersonType",
"any_one_of": [
"Contractor",
"SubContractor"
]
}
]
}
]
}
The above assigns groups membership basing on orgPersonType values:
Rules are additive, so permissions will only be granted for the rules that succeed. All the remote conditions of a rule must be valid.
When using multiple rules you can specify more than one effective user identification, but only the first match will be considered and the others ignored ordered from top to bottom.
Since rules are additive one can specify one user identification and this will also work. The best practice for multiple rules is to create a rule for just user and another rule for just groups. Below is rules example repeated but with global username mapping.
{
"rules": [
{
"local": [
"user": {
"id": "{0}"
}
],
"remote": [
{
"type": "UserType"
}
]
},
{
"local": [
{
"group": {
"name": "non-contractors",
"domain": {
"id": "abc1234"
}
}
}
],
"remote": [
{
"type": "orgPersonType",
"not_any_of": [
"Contractor",
"SubContractor"
]
}
]
},
{
"local": [
{
"group": {
"name": "contractors",
"domain": {
"id": "abc1234"
}
}
}
],
"remote": [
{
"type": "orgPersonType",
"any_one_of": [
"Contractor",
"SubContractor"
]
}
]
}
]
}
Keystone to Keystone federation also utilizes mappings, but has some differences.
An attribute file (/etc/shibboleth/attribute-map.xml) is used to add attributes to the Keystone Identity Provider. Attributes look as follows:
<Attribute name="openstack_user" id="openstack_user"/>
<Attribute name="openstack_user_domain" id="openstack_user_domain"/>
The Keystone Service Provider must contain a mapping as shown below. openstack_user, and openstack_user_domain match to the attribute names we have in the Identity Provider. It will map any user with the name user1 or admin in the openstack_user attribute and openstack_domain attribute default to a group with id abc1234.
{
rules = [
{
"local": [
{
"group": {
"id": "abc1234"
}
}
],
"remote": [
{
"type": "openstack_user",
"any_one_of": [
"user1",
"admin"
]
},
{
"type":"openstack_user_domain",
"any_one_of": [
"Default"
]
}
]
}
]
}
The possible attributes that can be used in a mapping are openstack_user, openstack_user_domain, openstack_roles, openstack_project, and openstack_project_domain.
Federate Keystone (SP) and an external IdP using OpenID Connect (mod_auth_openidc)
To install mod_auth_openidc on Ubuntu, perform the following:
sudo apt-get install libapache2-mod-auth-openidc
This module is available for other distributions (Fedora/CentOS/Red Hat) from: https://github.com/pingidentity/mod_auth_openidc/releases
In the keystone Apache site file, add the following as a top level option, to load the mod_auth_openidc module:
LoadModule auth_openidc_module /usr/lib/apache2/modules/mod_auth_openidc.so
Also within the same file, locate the virtual host entry and add the following entries for OpenID Connect:
<VirtualHost *:5000>
...
OIDCClaimPrefix "OIDC-"
OIDCResponseType "id_token"
OIDCScope "openid email profile"
OIDCProviderMetadataURL <url_of_provider_metadata>
OIDCClientID <openid_client_id>
OIDCClientSecret <openid_client_secret>
OIDCCryptoPassphrase openstack
OIDCRedirectURI http://localhost:5000/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/oidc/auth/redirect
<LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/oidc/auth>
AuthType openid-connect
Require valid-user
LogLevel debug
</LocationMatch>
</VirtualHost>
Note an example of an OIDCProviderMetadataURL instance is: https://accounts.google.com/.well-known/openid-configuration If not using OIDCProviderMetadataURL, then the following attributes must be specified: OIDCProviderIssuer, OIDCProviderAuthorizationEndpoint, OIDCProviderTokenEndpoint, OIDCProviderTokenEndpointAuth, OIDCProviderUserInfoEndpoint, and OIDCProviderJwksUri
Note, if using a mod_wsgi version less than 4.3.0, then the OIDCClaimPrefix must be specified to have only alphanumerics or a dash (“-”). This is because mod_wsgi blocks headers that do not fit this criteria. See http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed for more details
Once you are done, restart your Apache daemon:
$ service apache2 restart
Follow the steps outlined at: Running Keystone in HTTPD.
You’ll also need to install the Apache module mod_auth_mellon. For example:
$ apt-get install libapache2-mod-auth-mellon
Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:
Add WSGIScriptAlias directive to your vhost configuration:
WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1
Make sure the wsgi-keystone.conf contains a <Location> directive for the Mellon module and a <Location> directive for each identity provider
<Location /v3>
MellonEnable "info"
MellonSPPrivateKeyFile /etc/httpd/mellon/http_keystone.fqdn.key
MellonSPCertFile /etc/httpd/mellon/http_keystone.fqdn.cert
MellonSPMetadataFile /etc/httpd/mellon/http_keystone.fqdn.xml
MellonIdPMetadataFile /etc/httpd/mellon/idp-metadata.xml
MellonEndpointPath /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon
MellonIdP "IDP"
</Location>
<Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth>
AuthType "Mellon"
MellonEnable "auth"
</Location>
Note
Enable the Keystone virtual host, for example:
$ a2ensite wsgi-keystone.conf
Enable the ssl and auth_mellon modules, for example:
$ a2enmod ssl
$ a2enmod auth_mellon
Restart the Apache instance that is serving Keystone, for example:
$ service apache2 restart
Mellon provides a script called mellon_create_metadata.sh which generates the values for the config directives MellonSPPrivateKeyFile, MellonSPCertFile, and MellonSPMetadataFile. It is run like this:
$ mellon_create_metadata.sh http://keystone.fqdn:5000 \
http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon
The first parameter is used as the entity ID, a unique identifier for this Keystone SP. You do not have to use the URL, but it is an easy way to uniquely identify each Keystone SP. The second parameter is the full URL for the endpoint path corresponding to the parameter MellonEndpointPath.
Fetch your Service Provider’s Metadata file. This corresponds to the value of the MellonIdPMetadataFile directive above. For example:
$ wget --cacert /path/to/ca.crt -O /etc/httpd/mellon/idp-metadata.xml \
https://idp.fqdn/idp/saml2/metadata
Upload your Service Provider’s Metadata file to your Identity Provider. This is the file used as the value of the MellonSPMetadataFile in the config, generated by the mellon_create_metadata.sh script. The IdP may provide a webpage where you can upload the file, or you may be required to submit the file using wget or curl. Please check your IdP documentation for details.
Once you are done, restart the Apache instance that is serving Keystone, for example:
$ service apache2 restart
Follow the steps outlined at: Running Keystone in HTTPD.
You’ll also need to install Shibboleth, for example:
$ apt-get install libapache2-mod-shib2
Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:
Add WSGIScriptAlias directive to your vhost configuration:
WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1
Make sure the wsgi-keystone.conf contains a <Location> directive for the Shibboleth module and a <Location> directive for each identity provider:
<Location /Shibboleth.sso>
SetHandler shib
</Location>
<Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth>
ShibRequestSetting requireSession 1
ShibRequestSetting applicationId idp_1
AuthType shibboleth
ShibExportAssertion Off
Require valid-user
<IfVersion < 2.4>
ShibRequireSession On
ShibRequireAll On
</IfVersion>
</Location>
Note
Enable the Keystone virtual host, for example:
$ a2ensite wsgi-keystone.conf
Enable the ssl and shib2 modules, for example:
$ a2enmod ssl
$ a2enmod shib2
Restart Apache, for example:
$ service apache2 restart
Once you have your Keystone vhost (virtual host) ready, it’s then time to configure Shibboleth and upload your Metadata to the Identity Provider.
If new certificates are required, they can be easily created by executing:
$ shib-keygen -y <number of years>
The newly created file will be stored under /etc/shibboleth/sp-key.pem
You should fetch your Service Provider’s Metadata file. Typically this can be achieved by simply fetching a Metadata file, for example:
$ wget --no-check-certificate -O <name of the file> https://service.example.org/Shibboleth.sso/Metadata
Upload your Service Provider’s Metadata file to your Identity Provider. This step depends on your Identity Provider choice and is not covered here.
Configure your Service Provider by editing /etc/shibboleth/shibboleth2.xml file. You are advised to examine Shibboleth Service Provider Configuration documentation
An example of your /etc/shibboleth/shibboleth2.xml may look like (The example shown below is for reference only, not to be used in a production environment):
<!--
File configuration courtesy of http://testshib.org
More information:
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration
-->
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" clockSkew="1800 ">
<!-- The entityID is the name TestShib made for your SP. -->
<ApplicationDefaults entityID="https://<yourhosthere>/shibboleth">
<!--
You should use secure cookies if at all possible.
See cookieProps in this Wiki article.
-->
<!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions -->
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
relayState="ss:mem" handlerSSL="false">
<!-- Triggers a login request directly to the TestShib IdP. -->
<!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO -->
<SSO entityID="https://<idp-url>/idp/shibboleth" ECP="true">
SAML2 SAML1
</SSO>
<!-- SAML and local-only logout. -->
<!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceLogout -->
<Logout>SAML2 Local</Logout>
<!--
Handlers allow you to interact with the SP and gather
more information. Try them out!
Attribute value s received by the SP through SAML
will be visible at:
http://<yourhosthere>/Shibboleth.sso/Session
-->
<!--
Extension service that generates "approximate" metadata
based on SP configuration.
-->
<Handler type="MetadataGenerator" Location="/Metadata"
signing="false"/>
<!-- Status reporting service. -->
<Handler type="Status" Location="/Status"
acl="127.0.0.1"/>
<!-- Session diagnostic service. -->
<Handler type="Session" Location="/Session"
showAttributeValues="true"/>
<!-- JSON feed of discovery information. -->
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
</Sessions>
<!--
Error pages to display to yourself if
something goes horribly wrong.
-->
<Errors supportContact ="<admin_email_address>"
logoLocation="/shibboleth-sp/logo.jpg"
styleSheet="/shibboleth-sp/main.css"/>
<!--
Loads and trusts a metadata file that describes only one IdP
and how to communicate with it.
-->
<MetadataProvider type="XML" uri="<idp-metadata-file>"
backingFilePath="<local idp metadata>"
reloadInterval="180000" />
<!-- Attribute and trust options you shouldn't need to change. -->
<AttributeExtractor type="XML" validate="true"
path="attribute-map.xml"/>
<AttributeResolver type="Query" subjectMatch="true"/>
<AttributeFilter type="XML" validate="true"
path="attribute-policy.xml"/>
<!--
Your SP generated these credentials.
They're used to talk to IdP's.
-->
<CredentialResolver type="File" key="sp-key.pem"
certificate="sp-cert.pem"/>
<ApplicationOverride id="idp_1" entityID="https://<yourhosthere>/shibboleth">
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
relayState="ss:mem" handlerSSL="false">
<!-- Triggers a login request directly to the TestShib IdP. -->
<SSO entityID="https://<idp_1-url>/idp/shibboleth" ECP="true">
SAML2 SAML1
</SSO>
<Logout>SAML2 Local</Logout>
</Sessions>
<MetadataProvider type="XML" uri="<idp_1-metadata-file>"
backingFilePath="<local idp_1 metadata>"
reloadInterval="180000" />
</ApplicationOverride>
<ApplicationOverride id="idp_2" entityID="https://<yourhosthere>/shibboleth">
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
relayState="ss:mem" handlerSSL="false">
<!-- Triggers a login request directly to the TestShib IdP. -->
<SSO entityID="https://<idp_2-url>/idp/shibboleth" ECP="true">
SAML2 SAML1
</SSO>
<Logout>SAML2 Local</Logout>
</Sessions>
<MetadataProvider type="XML" uri="<idp_2-metadata-file>"
backingFilePath="<local idp_2 metadata>"
reloadInterval="180000" />
</ApplicationOverride>
</ApplicationDefaults>
<!--
Security policies you shouldn't change unless you
know what you're doing.
-->
<SecurityPolicyProvider type="XML" validate="true"
path="security-policy.xml"/>
<!--
Low-level configuration about protocols and bindings
available for use.
-->
<ProtocolProvider type="XML" validate="true" reloadChanges="false"
path="protocols.xml"/>
</SPConfig>
Keystone enforces external authentication when the REMOTE_USER environment variable is present so make sure Shibboleth doesn’t set the REMOTE_USER environment variable. To do so, scan through the /etc/shibboleth/shibboleth2.xml configuration file and remove the REMOTE_USER directives.
Examine your attributes map file /etc/shibboleth/attribute-map.xml and adjust your requirements if needed. For more information see attributes documentation
Once you are done, restart your Shibboleth daemon:
$ service shibd restart
$ service apache2 restart
Specify URLs of trusted horizon servers. This value may be repeated multiple times. This setting ensures that keystone only sends token data back to trusted servers. This is performed as a precaution, specifically to prevent man-in-the-middle (MITM) attacks.
[federation]
trusted_dashboard = http://acme.horizon.com/auth/websso/
trusted_dashboard = http://beta.horizon.com/auth/websso/
The /v3/auth/OS-FEDERATION/websso/<protocol> and /v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/websso routes must be protected by the chosen httpd module. This is performed so the request that originates from horizon will use the same identity provider that is configured in keystone.
Warning
By using the IdP specific route, a user will no longer leverage the Remote ID of a specific Identity Provider, and will be unable to verify that the Identity Provider is trusted, the mapping will remain as the only means to controlling authorization.
If mod_shib is used, then use the following as an example:
<VirtualHost *:5000>
...
<Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
AuthType shibboleth
Require valid-user
...
</Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso">
AuthType shibboleth
Require valid-user
...
</Location>
</VirtualHost>
If mod_auth_openidc is used, then use the following as an example:
<VirtualHost *:5000>
OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/websso/redirect
OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocol/oidc/websso/redirect
...
<Location ~ "/v3/auth/OS-FEDERATION/websso/oidc">
AuthType openid-connect
Require valid-user
...
</Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/oidc/websso">
AuthType openid-connect
Require valid-user
...
</Location>
</VirtualHost>
If mod_auth_kerb is used, then use the following as an example:
<VirtualHost *:5000>
...
<Location ~ "/v3/auth/OS-FEDERATION/websso/kerberos">
AuthType Kerberos
AuthName "Acme Corporation"
KrbMethodNegotiate on
KrbMethodK5Passwd off
Krb5Keytab /etc/apache2/http.keytab
...
</Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/kerberos/websso">
AuthType Kerberos
AuthName "Acme Corporation"
KrbMethodNegotiate on
KrbMethodK5Passwd off
Krb5Keytab /etc/apache2/http.keytab
...
</Location>
</VirtualHost>
If mod_auth_mellon is used, then use the following as an example:
<VirtualHost *:5000>
...
<Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
AuthType Mellon
MellonEnable auth
Require valid-user
...
</Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso">
AuthType Mellon
MellonEnable auth
Require valid-user
...
</Location>
</VirtualHost>
Note
If you are also using SSO via the API, don’t forget to make the Location settings match your configuration used for the keystone identity provider location: /v3/OS-FEDERATION/identity_providers/<idp>/protocols/<protocol>/auth
A remote id attribute indicates the header to retrieve from the WSGI environment. This header contains information about the identity of the identity provider. For mod_shib this would be Shib-Identity-Provider, for mod_auth_openidc, this could be HTTP_OIDC_ISS. For mod_auth_mellon, this could be MELLON_IDP.
It is recommended that this option be set on a per-protocol basis.
[saml2]
remote_id_attribute = Shib-Identity-Provider
[oidc]
remote_id_attribute = HTTP_OIDC_ISS
Alternatively, a generic option may be set at the [federation] level.
[federation]
remote_id_attribute = HTTP_OIDC_ISS
A keystone identity provider may have multiple remote_ids specified, this allows the same keystone identity provider resource to be used with multiple external identity providers. For example, an identity provider resource university-idp, may have the following remote_ids: ['university-x', 'university-y', 'university-z']. This removes the need to configure N identity providers in keystone.
This can be performed using the OS-FEDERATION API: PATCH /OS-FEDERATION/identity_providers/{idp_id}
Or by using the OpenStackClient CLI:
$ openstack identity provider set --remote-id <remote-id> <idp-id>
Note
Remote IDs are globally unique. Two identity providers cannot be associated with the same remote ID. Once authenticated with the external identity provider, keystone will determine which identity provider and mapping to use based on the protocol and the value returned from the remote_id_attribute key.
For example, if our identity provider is google, the mapping used is google_mapping and the protocol is oidc. The identity provider’s remote IDs would be: [accounts.google.com]. The remote_id_attribute value may be set to HTTP_OIDC_ISS, since this value will always be accounts.google.com.
The motivation for this approach is that there will always be some data sent by the identity provider (in the assertion or claim) that uniquely identifies the identity provider. This removes the requirement for horizon to list all the identity providers that are trusted by keystone.
Note
Django OpenStack Auth version 1.2.0 or higher is required for these steps.
Identity provider and federation protocol specific webSSO is only available in Django OpenStack Auth version 2.0.0 or higher.
Ensure the OPENSTACK_API_VERSIONS option in horizon’s local_settings.py has been updated to indicate that the identity version to use is 3.
OPENSTACK_API_VERSIONS = {
"identity": 3,
}
Ensure the OPENSTACK_KEYSTONE_URL option in horizon’s local_settings.py has been updated to point to a v3 URL.
OPENSTACK_KEYSTONE_URL = "http://localhost:5000/v3"
Ensure the WEBSSO_ENABLED option is set to True in horizon’s local_settings.py file, this will provide users with an updated login screen for horizon.
WEBSSO_ENABLED = True
Within horizon’s settings.py file, a list of supported authentication methods can be specified. The list includes Keystone federation protocols such as OpenID Connect and SAML, and also keys that map to specific identity provider and federation protocol combinations (as defined in WEBSSO_IDP_MAPPING). With the exception of credentials which is reserved by horizon, and maps to the user name and password used by keystone’s identity backend.
WEBSSO_CHOICES = (
("credentials", _("Keystone Credentials")),
("oidc", _("OpenID Connect")),
("saml2", _("Security Assertion Markup Language")),
("idp_1_oidc", "Acme Corporation - OpenID Connect"),
("idp_1_saml2", "Acme Corporation - SAML2")
)
A dictionary of specific identity provider and federation protocol combinations. From the selected authentication mechanism, the value will be looked up as keys in the dictionary. If a match is found, it will redirect the user to a identity provider and federation protocol specific WebSSO endpoint in keystone, otherwise it will use the value as the protocol_id when redirecting to the WebSSO by protocol endpoint.
WEBSSO_IDP_MAPPING = {
"idp_1_oidc": ("idp_1", "oidc"),
"idp_1_saml2": ("idp_1", "saml2")
}
Note
The value is expected to be a tuple formatted as: (<idp_id>, <protocol_id>).
The list set by the WEBSSO_CHOICES option will be generated in a drop-down menu in the login screen. The setting WEBSSO_INITIAL_CHOICE will automatically set that choice to be highlighted by default.
WEBSSO_INITIAL_CHOICE = "credentials"