Federated Identity¶
Keystone’s one-stop-shop for all federated identity documentation.
orphan: |
---|
Configuring Keystone for Federation¶
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)¶
Note
This feature is considered stable and supported as of the Juno release.
Prerequisites¶
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, or by using Keystone as an Identity Provider (IdP).
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 14.04 and Apache 2.4.7.
To enable federation, you’ll need to:
- Run keystone under Apache, rather than using uwsgi command.
- Configure Apache to use a federation capable authentication method.
- Configure Federation in Keystone.
Configure Apache to use a federation capable authentication method¶
There is currently support for two major federation protocols:
- SAML - Keystone supports the following implementations:
- Shibboleth - see Setup Shibboleth.
- Mellon - see Setup Mellon.
- OpenID Connect - see Setup OpenID Connect.
Configure keystone and Horizon for Single Sign-On¶
- To configure horizon to access a federated keystone, follow the steps outlined at: Keystone Federation and Horizon.
Configure Federation in Keystone¶
Now that the Identity Provider and keystone are communicating we can start to
configure federation
.
- Configure authentication drivers in keystone.conf
- Create keystone groups and assign roles
- Add Identity Provider(s), Mapping(s), and Protocol(s)
Configure authentication drivers in keystone.conf¶
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
Create keystone groups and assign roles¶
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.
For example, create a new domain and project like this:
$ openstack domain create federated_domain
$ openstack project create federated_project --domain federated_domain
And a new group like this:
$ openstack group create federated_users
Add the group to the domain and project:
$ openstack role add --group federated_users --domain federated_domain Member
$ openstack role add --group federated_users --project federated_project Member
We’ll later add a mapping that makes all federated users a part of this group and therefore members of the new domain.
Add Identity Provider(s), Mapping(s), and Protocol(s)¶
To utilize federation the following must be created in the Identity Service:
Read more about federation in keystone.
Identity Provider¶
Create an Identity Provider object in keystone, which represents the Identity Provider we will use to authenticate end users:
$ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp
The value for the remote-id
option is the Entity ID provided by the IdP. It
is the same value that you set for the SSO entityID in /etc/shibboleth/shibboleth2.xml.
If the IdP is a Keystone IdP, it is the value set in that Keystone’s
[saml]/idp_entity_id
option. It will usually appear as a URI but there
is no requirement for it to resolve to anything and may be arbitrarily decided
by the administrator of the IdP. The local name, here called ‘myidp’, is
decided by you and will be used by the mapping and protocol, and later for
authentication.
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.
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.
Read more about identity providers.
Mapping¶
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.
As a simple example, if keystone is your IdP, you can map a few known remote users to the group you already created:
$ cat > rules.json <<EOF
[
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"domain": {
"name": "Default"
},
"name": "federated_users"
}
}
],
"remote": [
{
"type": "openstack_user",
"any_one_of": [
"demo",
"alt_demo"
]
}
]
}
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping
As another example, if Shibboleth is your IdP, the remote section should use REMOTE_USER as the remote type:
$ 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
Read more about mapping.
Protocol¶
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.
You can create a protocol like this:
$ openstack federation protocol create mapped --mapping myidp_mapping --identity-provider myidp
The name you give the protocol is not arbitrary. It must match the method name
you gave in the [auth]/methods
config option. When authenticating it will be
referred to as the protocol_id
.
Read more about federation protocols
Performing federated authentication¶
Note
Authentication with keystone-to-keystone federation does not follow these steps. See Testing it all out to authenticate with keystone-to-keystone.
- Authenticate externally and generate an unscoped token in keystone
- Determine accessible resources
- Get a scoped token
Get an unscoped token¶
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 JSON format, with the ID in the X-Subject-Token header.
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.
Example cURL¶
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
Determine accessible resources¶
By using the previously returned token, the user can issue requests to the list projects and domains that are accessible.
- List projects a federated user can access:
GET /OS-FEDERATION/projects
- List domains a federated user can access:
GET /OS-FEDERATION/domains
Read more about listing resources.
Example cURL¶
$ 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
Get a scoped token¶
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.
Example cURL¶
$ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["mapped"],"mapped":{"id":"<unscoped_token_id>"}},"scope":{"project":{"domain": {"name": "federated_domain"},"name":"federated_project"}}}}' -D - http://localhost:5000/v3/auth/tokens
Keystone as an Identity Provider (IdP)¶
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
Configuration Options¶
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]
idp_entity_id=https://myidp.example.com/v3/OS-FEDERATION/saml2/idp
idp_sso_endpoint=https://myidp.example.com/v3/OS-FEDERATION/saml2/sso
idp_entity_id
is the unique identifier for the Identity Provider. It
usually takes the form of a URI but it does not have to resolve to anything.
idp_sso_endpoint
is required to generate valid metadata but its value is
not important, though it may be in the future.
Note the certfile
, keyfile
, and idp_metadata_path
settings and adjust them if
necessary:
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
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-555-5555
idp_contact_type=technical
Generate Metadata¶
In order to create a trust between the IdP and SP, metadata must be exchanged.
First, if you haven’t already generated a PKI key pair, you need to do so and
copy those files the locations designated by certfile
and keyfile
options that were assigned in the previous section. Ensure that your apache
vhost has SSL enabled and is using that keypair by adding the following to the
vhost:
SSLEngine on
SSLCertificateFile /etc/keystone/ssl/certs/signing_cert.pem
SSLCertificateKeyFile /etc/keystone/ssl/private/signing_key.pem
To create metadata for your keystone IdP, run the keystone-manage
command
and redirect 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.
Finally, restart apache.
Create a Service Provider (SP)¶
In this example we are creating a new Service Provider with an ID of mysp
,
a sp_url
of http://mysp.example.com/Shibboleth.sso/SAML2/ECP
and a
auth_url
of http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/auth
. The sp_url
will be used when creating a SAML assertion for mysp
and
signed by the current keystone IdP. The auth_url
is used to retrieve the
token for mysp
once the SAML assertion is sent. The auth_url has the format
described in Get an unscoped token.
$ 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/mapped/auth mysp
Testing it all out¶
Use keystoneauth to create a password session with the IdP, then use the session to authenticate with the SP, and get a scoped token from the SP.
Note
ECP stands for Enhanced Client or Proxy, an extension from the SAML2 protocol used in non-browser interfaces, like in the following example.
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)
orphan: |
---|
Mapping Combinations¶
Description¶
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.
Definitions¶
A rule hierarchy looks as follows:
{
"rules": [
{
"local": [
{
"<user> or <group>"
}
],
"remote": [
{
"<condition>"
}
]
}
]
}
- rules: top-level list of rules.
- local: a rule containing information on what local attributes will be mapped.
- remote: a rule containing information on what remote attributes will be mapped.
- <condition>: contains information on conditions that allow a rule, can only be set in a remote rule.
Mapping Rules¶
Mapping Engine¶
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>
Note
Although the rules file is formated as json the input file of assertion data is formatted as individual lines of key: value pairs, see keystone-manage mapping_engine –help for details.
Mapping Conditions¶
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.
Mappings Examples¶
The following are all examples of mapping rule types.
empty condition¶
{
"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
other conditions¶
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"
}
}
}
]
}
Output¶
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¶
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
.
Condition Combinations¶
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:
- any claim containing the key UserName.
- any claim containing key cn=IBM_Canada_Lab that doesn’t have the value <any_name>@naww.com.
- any claim containing key cn=IBM_USA_Lab that has value <any_name>@yeah.com.
Multiple Rules¶
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:
- neither
Contractor
norSubContractor
will belong to thenon-contractors
group. - either
Contractor or ``SubContractor
will belong to thecontractors
group.
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"
]
}
]
}
]
}
Auto-Provisioning¶
The mapping engine has the ability to aid in the auto-provisioning of resources when a federated user authenticates for the first time. This can be achieved using a specific mapping syntax that the mapping engine can parse and ultimately make decisions on.
For example, consider the following mapping:
{
"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"
}
]
}
]
}
The semantics of the remote
section have not changed. The difference
between this mapping and the other examples is the addition of a projects
section within the local
rules. The projects
list supplies a list
of projects that the federated user will be given access to. The projects
will be automatically created if they don’t exist when the user
authenticates and the mapping engine has applied values from the assertion
and mapped them into the local
rules.
In the above example, an authenticated federated user will be granted the
observer
role on the Production
project, member
role on the
Staging
project, and they will have admin
role on the Project for
jsmith
.
It is important to note the following constraints apply when auto-provisioning:
- Projects are the only resource that will be created dynamically.
- Projects will be created within the domain associated with the Identity Provider.
- The
projects
section of the mapping must also contain aroles
section.- Roles within the project must already exist in the deployment or domain.
- Assignments are actually created for the user which is unlike the ephemeral group memberships.
Since the creation of roles typically requires policy changes across other
services in the deployment, it is expected that roles are created ahead of
time. Federated authentication should also be considered idempotent if the
attributes from the SAML assertion have not changed. In the example from above,
if the user’s name is still jsmith
, then no new projects will be
created as a result of authentication.
Mappings can be created that mix groups
and projects
within the
local
section. The mapping shown in the example above does not contain a
groups
section in the local
rules. This will result in the federated
user having direct role assignments on the projects in the projects
list.
The following example contains local
rules comprised of both projects
and groups
, which allow for direct role assignments and group memberships.
{
"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"
}
]
}
]
}
In the above example, a federated user will receive direct role assignments on
the Marketing
project, as well as a dedicated project specific to the
federated user’s name. In addition to that, they will also be placed in the
Finance
group and receive all role assignments that group has on projects
and domains.
Keystone to Keystone¶
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.
orphan: |
---|
Setup OpenID Connect¶
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
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
Tips¶
- 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.
- Don’t forget to add oidc as an [auth] plugin in keystone.conf, see Configure authentication drivers in keystone.conf
orphan: |
---|
Setup Mellon¶
Configure Apache HTTPD for mod_auth_mellon¶
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 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/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
- See below for information about how to generate the values for the MellonSPMetadataFile, etc. directives.
saml2
may be different in your deployment, but do not use a wildcard value. Otherwise every federated protocol will be handled by Mellon.idp_1
has to be replaced with the name associated with the IdP in Keystone.- You are advised to carefully examine mod_auth_mellon Apache configuration documentation
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
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/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
orphan: |
---|
Setup Shibboleth¶
Configure Apache HTTPD for mod_shibboleth¶
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 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/mapped/auth>
ShibRequestSetting requireSession 1
AuthType shibboleth
ShibExportAssertion Off
Require valid-user
<IfVersion < 2.4>
ShibRequireSession On
ShibRequireAll On
</IfVersion>
</Location>
Note
mapped
is the name of the protocol that you will configuremyidp
is the name associated with the IdP in Keystone- The
ShibRequireSession
andShibRequireAll
rules are invalid in Apache 2.4+. - You are advised to carefully examine Shibboleth Apache configuration documentation
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.
orphan: |
---|
Setup Web Single Sign-On (SSO)¶
Keystone Changes¶
- 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/
- 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.
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/mapped">
AuthType shibboleth
Require valid-user
ShibRequestSetting requireSession 1
ShibRequireSession On
ShibExportAssertion Off
</Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/mapped/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/myidp/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/myidp/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/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/mapped">
AuthType Mellon
MellonEnable auth
Require valid-user
...
</Location>
<Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/mapped/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
- 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.
[mapped]
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
4. Copy the sso_callback_template.html template into the location specified by [federation]/sso_callback_template.
Horizon Changes¶
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.
- 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
- (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")),
("oidc", _("OpenID Connect")),
("mapped", _("Security Assertion Markup Language")),
("myidp_oidc", "Acme Corporation - OpenID Connect"),
("myidp_mapped", "Acme Corporation - SAML2")
)
- (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_oidc": ("myidp", "oidc"),
"myidp_mapped": ("myidp", "mapped")
}
Note
The value is expected to be a tuple formatted as: (<idp_id>, <protocol_id>).
- (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"