Federated Identity¶

Definitions¶

• Service Provider (SP): provides a service to an end-user.
• Identity Provider (IdP): service that stores information about users and groups.
• SAML assertion: contains information about a user as provided by an IdP.

Keystone as a Service Provider (SP)¶

[auth]
methods = external,password,token,saml2,openid

$ openstack domain create federated_domain
$ openstack project create federated_project --domain federated_domain

$ openstack group create federated_users

$ openstack role add --group federated_users --domain federated_domain Member
$ openstack role add --group federated_users --project federated_project Member

$ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp

$ cat > rules.json <<EOF
[
    {
        "local": [
            {
                "user": {
                    "name": "{0}"
                },
                "group": {
                    "domain": {
                        "name": "Default"
                    },
                    "name": "federated_users"
                }
            }
        ],
        "remote": [
            {
                "type": "openstack_user"
            },
            {
                "type": "openstack_user",
                "any_one_of": [
                    "demo",
                    "alt_demo"
                ]
            }
        ]
    }
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping

$ cat > rules.json <<EOF
[
    {
        "local": [
            {
                "user": {
                    "name": "{0}"
                },
                "group": {
                    "domain": {
                        "name": "Default"
                    },
                    "name": "federated_users"
                }
            }
        ],
        "remote": [
            {
                "type": "REMOTE_USER"
            }
        ]
    }
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping

$ openstack federation protocol create saml2 --mapping myidp_mapping --identity-provider myidp

$ curl -X GET -D - http://localhost:5000/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth

$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_URL=http://localhost:5000/v3
$ openstack federation project list

$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_URL=http://localhost:5000/v3
$ openstack federation domain list

$ export OS_AUTH_TYPE=token
$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_AUTH_URL=http://localhost:5000/v3
$ export OS_PROJECT_DOMAIN_NAME=federated_domain
$ export OS_PROJECT_NAME=federated_project
$ openstack token issue

Keystone as an Identity Provider (IdP)¶

$ apt-get install xmlsec1

[saml]
idp_entity_id=https://myidp.example.com/v3/OS-FEDERATION/saml2/idp
idp_sso_endpoint=https://myidp.example.com/v3/OS-FEDERATION/saml2/sso

certfile=/etc/keystone/ssl/certs/signing_cert.pem
keyfile=/etc/keystone/ssl/private/signing_key.pem
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml

idp_organization_name=example_company
idp_organization_display_name=Example Corp.
idp_organization_url=example.com

idp_contact_company=example_company
idp_contact_name=John
idp_contact_surname=Smith
idp_contact_email=jsmith@example.com
idp_contact_telephone=555-555-5555
idp_contact_type=technical

SSLEngine on
SSLCertificateFile /etc/keystone/ssl/certs/signing_cert.pem
SSLCertificateKeyFile /etc/keystone/ssl/private/signing_key.pem

$ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml

$ openstack service provider create --service-provider-url 'http://mysp.example.com/Shibboleth.sso/SAML2/ECP' --auth-url http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth mysp

import os

from keystoneauth1 import session
from keystoneauth1.identity import v3
from keystoneauth1.identity.v3 import k2k

auth = v3.Password(auth_url=os.environ.get('OS_AUTH_URL'),
                   username=os.environ.get('OS_USERNAME'),
                   password=os.environ.get('OS_PASSWORD'),
                   user_domain_name=os.environ.get('OS_USER_DOMAIN_NAME'),
                   project_name=os.environ.get('OS_PROJECT_NAME'),
                   project_domain_name=os.environ.get('OS_PROJECT_DOMAIN_NAME'))
password_session = session.Session(auth=auth)
k2ksession = k2k.Keystone2Keystone(password_session.auth, 'mysp',
                                   domain_name='federated_domain')
auth_ref = k2ksession.get_auth_ref(password_session)
scoped_token_id = auth_ref.auth_token
print('Scoped token id: %s' % scoped_token_id)

Description¶

During the authentication process an identity provider (IdP) will present keystone with a set of user attributes about the user that is authenticating. For example, in the SAML2 flow this comes to keystone in the form of a SAML document.

The attributes are typically processed by third-party software and are presented to keystone as environment variables. The original document from the IdP is generally not available to keystone. This is how the Shibboleth and Mellon implementations work.

The mapping format described in this document maps these environment variables to a local keystone user. The mapping may also define group membership for that user and projects the user can access.

An IdP has exactly one mapping specified per protocol. Mappings themselves can be used multiple times by different combinations of IdP and protocol.

Definitions¶

A mapping looks as follows:

{
    "rules": [
        {
            "local": [
                {
                    <user>
                    [<group>]
                    [<project>]
                }
            ],
            "remote": [
                {
                    <match>
                    [<condition>]
                }
            ]
        }
    ]
}

• mapping: a JSON object containing a list of rules.
• rules: a property in the mapping that contains the list of rules.
• rule: a JSON object containing local and remote properties to define the rule. There is no explicit rule property.
• local: a JSON object containing information on what local attributes will be mapped. The mapping engine processes this using the context (defined below) and the result is a representation of the user from keystone’s perspective.
  • <user>: the local user that will be mapped to the federated user.
  • <group>: (optional) the local groups the federated user will be placed in.
  • <projects>: (optional) the local projects mapped to the federated user.
• remote: a JSON object containing information on what remote attributes will be mapped.
  • <match>: a JSON object that tells the mapping engine what federated attribute to make available for substitution in the local object. There can be one or more of these objects in the remote list.
  • <condition>: a JSON object containing conditions that allow a rule. There can be zero or more of these objects in the remote list.
• direct mapping: the mapping engine keeps track of each match and makes them available to the local rule for substitution.
• assertion: data provided to keystone by the IdP to assert facts (name, groups, etc) about the authenticating user. This is an XML document when using the SAML2 protocol.
• mapping context: the data, represented as key-value pairs, that is used by the mapping engine to turn the local object into a representation of the user from keystone’s perspective. The mapping context contains the environment of the keystone process and any direct mapping values calculated when processing the remote list.

How Mappings Are Processed¶

A mapping is selected by IdP and protocol. Then keystone takes the mapping and processes each rule sequentially stopping after the first matched rule. A rule is matched when all of its conditions are met.

First keystone evaluates each condition from the rule’s remote property to see if the rule is a match. If it is a match, keystone saves the data captured by each of the matches from the rule’s remote property in an ordered list. We call these matches direct mappings since they can be used in the next step.

After the rule is found using the rule’s conditions and a list of direct mappings is stored, keystone begins processing the rule’s local property. Each object in the local property is collapsed into a single JSON object. For example:

{
    "local": [
        {
            "user": {...}
        },
        {
            "projects": [...]
        },
    ]
}

becomes:

{
    "local": {
        "user": {...}
        "projects": [...]
    },
}

when the same property exists in the local multiple times the first occurrence wins:

{
    "local": [
        {
            "user": {#first#}
        },
        {
            "projects": [...]
        },
        {
            "user": {#second#}
        },
    ]
}

becomes:

{
    "local": {
        "user": {#first#}
        "projects": [...]
    },
}

We take this JSON object and then recursively process it in order to apply the direct mappings. This is simply looking for the pattern {#} and substituting it with values from the direct mappings list. The index of the direct mapping starts at zero.

Mapping Rules¶

$ keystone-manage mapping_engine --rules <file> --input <file>

{
    "rules": [
        {
            "local": [
                {
                    "user": {
                        "name": "{0} {1}",
                        "email": "{2}"
                    },
                    "group": {
                        "name": "{3}",
                        "domain": {
                            "id": "0cd5e9"
                        }
                    }
                }
            ],
            "remote": [
                {
                    "type": "FirstName"
                },
                {
                    "type": "LastName"
                },
                {
                    "type": "Email"
                },
                {
                    "type": "OIDC_GROUPS"
                }
            ]
        }
    ]
}

- 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

{
    "rules": [
        {
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    },
                    "group": {
                        "id": "0cd5e9"
                    }
                }
            ],
            "remote": [
                {
                    "type": "UserName"
                },
                {
                    "type": "HTTP_OIDC_GROUPIDS",
                    "<other_condition>": [
                        "HTTP_OIDC_EMAIL"
                    ]
                }
            ]
        }
    ]
}

{
    "rules": [
        {
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    }
                },
                {
                    "groups": "{1}",
                    "domain": {
                        "id": "0cd5e9"
                    }
                }
            ],
            "remote": [
                {
                    "type": "UserName"
                },
                {
                    "type": "HTTP_OIDC_GROUPIDS",
                    "<other_condition>": [
                        "me@example.com"
                    ]
                }
            ]
        }
    ]
}

{
    "local": [
        {
            "group": {
                "id":"0cd5e9"
            }
        }
    ]
}

{
    "local": [
        {
            "group": {
                "name": "developer_group",
                "domain": {
                    "id": "abc1234"
                }
            }
        }
    ]
}

{
    "local": [
        {
            "group": {
                "name": "developer_group",
                "domain": {
                    "name": "private_cloud"
                }
            }
        }
    ]
}

{
    "local": [
        {
            "user": {
                "name": "local_user",
                "type": "local",
                "domain": {
                    "name": "local_domain"
                }
            }
        }
    ]
}

{
    "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>]"
                    }
            }
        ]
}

{
    "rules": [
        {
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    },
                    "group": {
                        "id": "0cd5e9"
                    }
                },
            ],
            "remote": [
                {
                    "type": "UserName"
                },
                {
                    "type": "HTTP_OIDC_GROUPIDS",
                    "any_one_of": [
                        ".*@yeah.com$"
                    ]
                    "regex": true
                }
            ]
        }
    ]
}

{
    "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
                }
            ]
        }
    ]
}

{"UserName":"<any_name>@yeah.com"}
{"cn=IBM_USA_Lab":"<any_name>@yeah.com"}
{"cn=IBM_Canada_Lab":"<any_name>@yeah.com"}

{
    "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"
                    ]
                }
            ]
        }
    ]
}

{
    "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"
            ]
        }]
    }]
 }

{
    "rules": [
        {
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    }
                },
                {
                    "projects": [
                        {
                            "name": "Production",
                            "roles": [
                                {
                                    "name": "observer"
                                }
                            ]
                        },
                        {
                            "name": "Staging",
                            "roles": [
                                {
                                    "name": "member"
                                }
                            ]
                        },
                        {
                            "name": "Project for {0}",
                            "roles": [
                                {
                                    "name": "admin"
                                }
                            ]
                        }
                    ]
                }
            ],
            "remote": [
                {
                    "type": "UserName"
                }
            ]
        }
    ]
}

{
    "rules": [
        {
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    }
                },
                {
                    "projects": [
                        {
                            "name": "Marketing",
                            "roles": [
                                {
                                    "name": "member"
                                }
                            ]
                        },
                        {
                            "name": "Development project for {0}",
                            "roles": [
                                {
                                    "name": "admin"
                                }
                            ]
                        }
                    ]
                },
                {
                    "group": {
                        "name": "Finance",
                        "domain": {
                            "id": "6fe767"
                        }
                    }
                }
            ],
            "remote": [
                {
                    "type": "UserName"
                }
            ]
        }
    ]
}

<!-- example from a K2k Shibboleth implementation -->
<Attribute name="openstack_user" id="openstack_user"/>
<Attribute name="openstack_user_domain" id="openstack_user_domain"/>

{
    "rules": [
        {
            "local": [
                {
                    "group": {
                        "id": "abc1234"
                    }
                }
            ],
            "remote": [
                {
                    "type": "openstack_user",
                    "any_one_of": [
                        "user1",
                        "admin"
                    ]
                },
                {
                    "type":"openstack_user_domain",
                    "any_one_of": [
                        "Default"
                    ]
                }
            ]
        }
    ]
}

Configuring mod_auth_openidc¶

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

Enable the auth_openidc module:

$ sudo a2enmod auth_openidc

In the keystone vhost 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/openid/auth

    <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/openid/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:

$ sudo service apache2 restart

Tips¶

1. When creating a mapping, note that the ‘remote’ attributes will be prefixed, with HTTP_, so for instance, if you set OIDCClaimPrefix to OIDC-, then a typical remote value to check for is: HTTP_OIDC_ISS.
2. Don’t forget to add openid as an [auth] plugin in keystone.conf, see Configure authentication drivers in keystone.conf

Configure Apache HTTPD for mod_auth_mellon¶

Follow the steps outlined at: Keystone install guide for SUSE, RedHat or Ubuntu.

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 this WSGIScriptAlias directive to your public vhost configuration:

WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$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/apache2/mellon/http_keystone.fqdn.key
    MellonSPCertFile /etc/apache2/mellon/http_keystone.fqdn.cert
    MellonSPMetadataFile /etc/apache2/mellon/http_keystone.fqdn.xml
    MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
    MellonEndpointPath /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon
    MellonIdP "IDP"
</Location>

<Location /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth>
    AuthType "Mellon"
    MellonEnable "auth"
</Location>

Enable the auth_mellon module, for example:

$ a2enmod auth_mellon

Configuring the Mellon SP Metadata¶

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/myidp/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. Note that the metadata generated by this script includes a signing key but not an encryption key, and your IdP (such as testshib.org) may require an encryption key. Simply change the node <KeyDescriptor use=”signing”> to <KeyDescriptor use=”encryption”> or add another key to the file. Check your IdP documentation for details.

After generating the keypair and metadata, copy the files to the locations given in the Mellon directives in your apache configs.

Upload the Service Provider’s Metadata file which you just generated to your Identity Provider. This is the file used as the value of the MellonSPMetadataFile in the config. 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.

Fetch your Identity Provider’s Metadata file and copy it to the path specified by the MellonIdPMetadataFile directive above. For example:

$ wget --cacert /path/to/ca.crt -O /etc/apache2/mellon/idp-metadata.xml \
  https://idp.fqdn/idp/saml2/metadata

Once you are done, restart the Apache instance that is serving Keystone, for example:

$ service apache2 restart

Configure Apache HTTPD for mod_shibboleth¶

Follow the steps outlined at: Running Keystone in HTTPD for SUSE, RedHat or Ubuntu.

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 this WSGIScriptAliasMatch directive to your public vhost configuration:

WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$1

Make sure the keystone.conf vhost file 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/myidp/protocols/saml2/auth>
    ShibRequestSetting requireSession 1
    AuthType shibboleth
    ShibExportAssertion Off
    Require valid-user

    <IfVersion < 2.4>
        ShibRequireSession On
        ShibRequireAll On
   </IfVersion>
</Location>

Enable the shib2 module, for example:

$ a2enmod shib2

Restart Apache, for example:

$ service apache2 restart

Configuring shibboleth2.xml¶

Once you have your Keystone vhost (virtual host) ready, it’s then time to configure Shibboleth and upload your Metadata to the Identity Provider.

Create a new keypair for Shibboleth with:

$ shib-keygen -y <number of years>

The newly created key file will be stored under /etc/shibboleth/sp-key.pem.

Configure your Service Provider by editing /etc/shibboleth/shibboleth2.xml file. You will want to change five settings:

• Set the SP entity ID. This value usually has the form of a URI but it does not have to resolve to anything. It must uniquely identify your Service Provider to your Identity Provider.

<ApplicationDefaults entityID="http://mysp.example.com/shibboleth">

• Set the IdP entity ID. This value is determined by the IdP. For example, if Keystone is the IdP:

<SSO entityID="https://myidp.example.com/v3/OS-FEDERATION/saml2/idp">

Example if testshib.org is the IdP:

<SSO entityID="https://idp.testshib.org/idp/shibboleth">

• Remove the discoveryURL lines unless you want to enable advanced IdP discovery.
• Add a MetadataProvider block. The URI given here is a real URL that Shibboleth will use to fetch metadata from the IdP. For example, if Keystone is the IdP:

<MetadataProvider type="XML" uri="https://myidp.example.com:5000/v3/OS-FEDERATION/saml2/metadata"/>

Example if testshib.org is the IdP:

<MetadataProvider type="XML" uri="http://www.testshib.org/metadata/testshib-providers.xml" />

You are advised to examine Shibboleth Service Provider Configuration documentation

The result should look like (The example shown below is for reference only, not to be used in a production environment):

<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    clockSkew="180">

    <!--
    By default, in-memory StorageService, ReplayCache, ArtifactMap, and SessionCache
    are used. See example-shibboleth2.xml for samples of explicitly configuring them.
    -->

    <!--
    To customize behavior for specific resources on Apache, and to link vhosts or
    resources to ApplicationOverride settings below, use web server options/commands.
    See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfigurationElements for help.

    For examples with the RequestMap XML syntax instead, see the example-shibboleth2.xml
    file, and the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHowTo topic.
    -->

    <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
    <ApplicationDefaults entityID="https://mysp.example.com/shibboleth">

        <!--
        Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
        You MUST supply an effectively unique handlerURL value for each of your applications.
        The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
        a relative value based on the virtual host. Using handlerSSL="true", the default, will force
        the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
        Note that while we default checkAddress to "false", this has a negative impact on the
        security of your site. Stealing sessions via cookie theft is much easier with this disabled.
        -->
        <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                  checkAddress="false" handlerSSL="false" cookieProps="http">

            <!--
            Configures SSO for a default IdP. To allow for >1 IdP, remove
            entityID property and adjust discoveryURL to point to discovery service.
            (Set discoveryProtocol to "WAYF" for legacy Shibboleth WAYF support.)
            You can also override entityID on /Login query string, or in RequestMap/htaccess.
            -->
            <SSO entityID="https://myidp.example.com/v3/OS-FEDERATION/saml2/idp">
              SAML2 SAML1
            </SSO>

            <!-- SAML and local-only logout. -->
            <Logout>SAML2 Local</Logout>

            <!-- 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 ::1"/>

            <!-- Session diagnostic service. -->
            <Handler type="Session" Location="/Session" showAttributeValues="false"/>

            <!-- JSON feed of discovery information. -->
            <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
        </Sessions>
        <!--
        Allows overriding of error template information/filenames. You can
        also add attributes with values that can be plugged into the templates.
        -->
        <Errors supportContact="root@localhost"
            helpLocation="/about.html"
            styleSheet="/shibboleth-sp/main.css"/>

        <!-- Example of remotely supplied batch of signed metadata. -->
        <!--
        <MetadataProvider type="XML" uri="http://federation.org/federation-metadata.xml"
              backingFilePath="federation-metadata.xml" reloadInterval="7200">
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
            <MetadataFilter type="Signature" certificate="fedsigner.pem"/>
        </MetadataProvider>
        -->

        <!-- Example of locally maintained metadata. -->
        <!--
        <MetadataProvider type="XML" file="partner-metadata.xml"/>
        -->
        <MetadataProvider type="XML" uri="https://myidp.example.com:5000/v3/OS-FEDERATION/saml2/metadata"/>

        <!-- Map to extract attributes from SAML assertions. -->
        <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>

        <!-- Use a SAML query if no attributes are supplied during SSO. -->
        <AttributeResolver type="Query" subjectMatch="true"/>

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->
        <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>

        <!-- Simple file-based resolver for using a single keypair. -->
        <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>

        <!--
        The default settings can be overridden by creating ApplicationOverride elements (see
        the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApplicationOverride topic).
        Resource requests are mapped by web server commands, or the RequestMapper, to an
        applicationId setting.
        Example of a second application (for a second vhost) that has a different entityID.
        Resources on the vhost would map to an applicationId of "admin":
        -->
        <!--
        <ApplicationOverride id="admin" entityID="https://admin.example.org/shibboleth"/>
        -->
    </ApplicationDefaults>

    <!-- Policies that determine how to process and authenticate runtime messages. -->
    <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>

If keystone is your IdP, you will need to examine your attributes map file /etc/shibboleth/attribute-map.xml and add the following attributes:

<Attribute name="openstack_user" id="openstack_user"/>
<Attribute name="openstack_roles" id="openstack_roles"/>
<Attribute name="openstack_project" id="openstack_project"/>
<Attribute name="openstack_user_domain" id="openstack_user_domain"/>
<Attribute name="openstack_project_domain" id="openstack_project_domain"/>

For more information see the attributes documentation

Once you are done, restart your Shibboleth daemon and apache:

$ service shibd restart
$ service apache2 restart

Check /var/log/shibboleth/shibd_warn.log for any ERROR or CRIT notices and correct them.

Upload your Service Provider’s metadata file to your Identity Provider. You can fetch it with:

$ wget http://mysp.example.com/Shibboleth.sso/Metadata

This step depends on your Identity Provider choice and is not covered here. If keystone is your Identity Provider you do not need to upload this file.

Keystone Changes¶

1. Update trusted_dashboard in keystone.conf.

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/

2. Update httpd vhost file with websso information.

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.

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
      ShibRequestSetting requireSession 1
      ShibRequireSession On
      ShibExportAssertion Off
    </Location>
    <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/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
    OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/openid/websso

    ...

    <Location ~ "/v3/auth/OS-FEDERATION/websso/openid">
      AuthType openid-connect
      Require valid-user
      ...
    </Location>
    <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/openid/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/myidp/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/myidp/protocols/saml2/websso">
      AuthType Mellon
      MellonEnable auth
      Require valid-user
      ...
    </Location>
</VirtualHost>

3. Update remote_id_attribute in keystone.conf.

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
[openid]
remote_id_attribute = HTTP_OIDC_ISS

Alternatively, a generic option may be set at the [federation] level.

[federation]
remote_id_attribute = HTTP_OIDC_ISS

4. Copy the sso_callback_template.html template into the location specified by [federation]/sso_callback_template.

Horizon Changes¶

1. Set the WEBSSO_ENABLED option.

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

2. (Optional) Create a list of authentication methods with the WEBSSO_CHOICES option.

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")),
      ("openid", _("OpenID Connect")),
      ("saml2", _("Security Assertion Markup Language")),
      ("myidp_openid", "Acme Corporation - OpenID Connect"),
      ("myidp_saml2", "Acme Corporation - SAML2")
    )

3. (Optional) Create a dictionary of specific identity provider and federation protocol combinations.

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 = {
      "myidp_openid": ("myidp", "openid"),
      "myidp_saml2": ("myidp", "saml2")
    }

6. (Optional) Specify an initial choice with the WEBSSO_INITIAL_CHOICE option.

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"

7. Restart your web server:

$ sudo service apache2 restart