Federations Configuration

The Federation module is used to integrate Verify Identity Access with third party applications to provide or accept identity information. This module can be use for both: supplying third party applications with identity information (Verify Identity Access is the identity source); or accepting identity information (Verify Identity Access is the identity consumer).

Integration with third party applications is achieved via Identity standards, such as OIDC or SAML 2.0.

Example

attribute_sources:
- name: "SF_IDPEmail"
  type: "value"
  value: "user@verify-demoer-dev-ed.salesforce.com"
- name: "IDPEmail"
  type: "value"
  value: "user@verify.securitypoc.com"
- name: "ImmutableID"
  type: "value"
  value: "verifytestuser"
federations:
- name: "SP-SAML-QC"
  protocol: "SAML2_0"
  template_name: "QuickConnect"
  point_of_contact_url: "https://www.myidp.ibmsec/isva"
  provider_id: ""
  decrypt_keystore: "rt_profile_keys"
  decrypt_key_label: "server"
  signing_keystore: "rt_profile_keys"
  signing_key_label: "runtime"
  sso_service_binding: "redirect"
  partners:
  - name: "Salesforce"
    role: "sp"
    client_auth_method: "none"
    template_name: "Salesforce_JIT_Provisioning_Disabled"
    enabled: true
    acs:
      binding: "post"
      default: true
      index: 0
      url: "https://verify-demoer-dev-ed.my.salesforce.com"
    validate_authn_request: true
    validation:
      keystore: "rt_profile_keys"
      key_label: "Verify_19.crt"
    attribute_mapping:
      name: "IDP_Email"
      source: "3"
    active_delegate_id: "default-map"
    provider_id: "https://verify-demoer-dev-ed.my.salesforce.com"
    signature_validation: false
    mapping_rule: "mapping/rules/federations/adv_attribute_mapping.js"
  - name: "Micrsoft Office 365"
    template_name: "Office_365"
    role: "sp"
    enabled: true
    acs:
      binding: "post"
      default: true
      index: "0"
      url: "https://login.microsoftonline.com/login.srf"
    validate_authn_request: false
    attribute_mapping:
    - name: "IDPEmail"
      source: "1"
    - name: "ImmutableID"
      source: "2"
    active_delegate_id: "default-map"
    provider_id: "urn:federation:MicrosoftOnline"
    signature_validation: false
    mapping_rule: "mapping/rules/federations/adv_attribute_mapping.js"
               - name: "SP-SAML-CIC"
  role: "ip"
  protocol: "SAML2_0"
  provider_id: ""
  point_of_contact_url: "https://www.myidp.ibmsec/isva"
  template_name: ""
  company_name: "CIC"
  decrypt_keystore: "rt_profile_keys"
  decrypt_key_label: "runtime"
  signing_keystore: "rt_profile_keys"
  signing_key_label: "runtime"
  validate_authn_request: true
  sso_service_binding: "post"
  active_delegate_id: "skip-identity-map"
  need_consent_to_federate: false
  message_issuer_format: ""
  partners:
  - name: "securitypoc.ice.ibmcloud.com"
    role: "sp"
    enabled: true
    acs:
    - binding: "post"
      default: false
      index: "1"
      url: "https://securitypoc.ice.ibmcloud.com/saml/sps/saml20sp/saml20/login"
    - binding: "redirect"
      default: false
      index: "2"
      url: "https://securitypoc.ice.ibmcloud.com/saml/sps/saml20sp/saml20/login"
    single_logout_service:
    - binding: "post"
      url: "https://securitypoc.ice.ibmcloud.com/saml/sps/saml20sp/saml20/slo"
    - binding: "redirect"
      url: "https://securitypoc.ice.ibmcloud.com/saml/sps/saml20sp/saml20/slo"
    validate:
      authn_request: true
      logout_request: true
      logout_response: false
      keystore: "rt_profile_keys"
      key_label: "validation-encryption-1501211921641.cer"
    encryption:
      keystore: "rt_profile_keys"
      key_label: "validation-encryption-1501211921641.cer"
      block_encryption_algorithm: "AES-128"
      key_transport_algorithm: "RSA-OAEP"
    provider_id: "https://securitypoc.ice.ibmcloud.com/saml/sps/saml20sp/saml20"
    signature_algorithm: "RSA-SHA1"
    signature_digest_algorithm: "SHA1"
  reverse_proxy: "default-proxy"
- name: "OIDCRP-IBMid"
  protocol: "OIDCRP"
  redirect_uri_prefix: "https://login.ibm.com/oidc"
  response_types:
  - "code"
  active_delegate_id: "default-map"
  mapping_rule: "mapping/rules/federations/verify_ibm_id.js"
  advanced_configuration_active_delegate: "default-map"
  advanced_configuration_mapping_rule: "mapping/rules/federations/verify_ibm_id_adv.js"
  partners:
  - name: "IBMid-AuthorizationCode"
    enabled: true
    client_id: !secret default/isva-secrets:ibmid_client_id
    client_secret: !secret default/isva-secrets:ibmid_client_secret
    metadata_endpoint: "https://login.ibm.com/oidc/endpoint/default/.well-known/openid-configuration"
    scope:
    - "openid"
    token_endpoint_auth_method: "client_secret_post"
    signing_algorithm: "RS256i"
  reverse_proxy: "default-proxy"

Point Of Contact

To configure Point of Contact profiles, see the entry in the Appliance or Container documentation.

Alias Service

Expand all Collapse all

Type: object

The alias service stores and retrieves aliases that are related to a federated identity. Persistent name identifier format allows you to link a user at the identity provider with a user at the service provider. Verify Identity Access stores these account linkages in a high-volume database or an LDAP database.

Example:

alias_service:
  ldap_connection: LocalLDAP
  aliases:
  - username: mary
    federation_id: https://mysp.com/isam/sps/samlsp/saml20
    type: partner
    aliases:
    - mary@ibm.com
    - mary@au.ibm.com

db_type Required

Type: enum (of string)

The alias database type.

Must be one of:

• "JDBC"
• "LDAP"

ldap_connection Required

Type: string

The LDAP server connection name.

ldap_base_dn Required

Type: string

The baseDN to search for the user entry.

aliases

Type: array

The SAML aliases to create.

No Additional Items

Each item of this array must be:

Type: object

An alias association for a user in a federation.

username Required

Type: string

The user to associate aliases with.

federation Required

Type: string

The federation this alias is for.

partner

Type: string

Optionally, specify a partner as well as a federation.

type

Type: enum (of string) Default: "self"

The type of the aliases. Defaults to 'self'.

Must be one of:

• "self"
• "partner"
• "old"

aliases Required

Type: array of string

An array of aliases to associate with the user.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

Type: string

Attribute Sources

To set Attribute sources, see the entry in the Appliance or Container documentation.

Access Policies

To set Access policy configuration, see the entry in the Appliance or Container documentation.

Security Token Service

Expand all Collapse all

Type: object

Configuration for Security Token Service (STS) chain templates and chains for security token transformation and validation.

Example:

sts:
  chain_templates:
  - name: UsernameTokentoSAML20
    description: Maps from UsernameToken to SAML20
    modules:
    - id: Default UserNameToken
      mode: validate
    - id: Default Map Module
      mode: map
    - id: Default SAML 2.0 Token
      mode: issue
  - name: STSUUtoSTSUU
    description: STSUU to STSUU
    modules:
    - id: Default STSUU
      mode: validate
    - id: Default Map Module
      mode: map
    - id: Default STSUU
      mode: issue
  chains:
  - name: SAML20ToSAML20Chain
    description: Chain for saml20 to saml20
    chain_template: SAML20tpSAML20
    request_type: validate
    applies_to:
      address: http://appliesto/saml20
    issuer:
      address: http://issuer/saml20
    sign_responses: false
    properties:
      myself:
      - name: com.tivoli.am.fim.sts.saml.2.0.assertion.replay.validation
        index: 0
        value:
        - 'false'
      - name: map.rule.reference.name
        index: 1
        value:
        - saml20_to_saml20

chain_templates

Type: array

List of STS chain templates to create or update.

No Additional Items

Each item of this array must be:

Type: object

An STS Chain Template defining the sequence of modules for token transformation.

name Required

Type: string

A friendly name for the STS Chain Template.

description Required

Type: string

A description of the STS Chain Template.

modules Required

Type: array

An array of the modules that make up the STS Chain Template.

No Additional Items

Each item of this array must be:

Type: object

A module item in an STS Chain Template.

id Required

Type: string

The token id of an STS module.

mode Required

Type: enum (of string)

The mode the STS module is used in in the chain. Must be one of the supported modes of the STS module.

Must be one of:

• "validate"
• "map"
• "issue"

prefix

Type: string

The prefix for the chain item.

chains

Type: array

List of STS chains to create or update.

No Additional Items

Each item of this array must be:

Type: object

An STS Chain that references a Chain Template and defines specific configuration.

name Required

Type: string

A friendly name for the STS Chain.

description Required

Type: string

A description of the STS Chain.

chain_template Required

Type: string

The name of the STS Chain Template that is referenced by this STS Chain.

request_type Required

Type: enum (of string)

The type of request to associate with this chain. The request is one of the types that are supported by the WS-Trust specification.

Must be one of:

• "validate"
• "issue"
• "renew"
• "cancel"

token_type

Type: string

The STS module type to map a request message to an STS Chain Template.

xpath

Type: string

The custom lookup rule in XML Path Language to map a request message to an STS Chain Template.

sign_responses

Type: boolean

Whether to sign the Trust Server SOAP response messages.

signature

Type: object

The key to sign the Trust Server SOAP response messages.

store Required

Type: string

The certificate database name.

label Required

Type: string

The certificate or key label.

validate_requests

Type: boolean

Whether requires a signature on the received SOAP request message that contains the RequestSecurityToken message.

validation_key

Type: object

The key to validate the received SOAP request message.

Same definition as signature

send_validation_confirmation

Type: boolean

Whether to send signature validation confirmation.

issuer

Type: object

The issuer of the token.

address Required

Type: stringFormat: uri

The URI of the company or enterprise.

port_type_namespace

Type: stringFormat: uri

The namespace URI part of a qualified name for a Web service port type.

port_type_name

Type: string

The local part of a qualified name for a Web service port type.

service_namespace

Type: stringFormat: uri

The namespace URI part of a qualified name for a Web service.

service_name

Type: string

The local part of a qualified name for a Web service.

applies_to

Type: object

The scope of the token.

Same definition as issuer

properties

Type: object

The properties for all modules within the STS Chain Template referenced in the STS Chain.

attributes

Type: array

Attribute mappings for the chain.

No Additional Items

Each item of this array must be:

Type: object

An attribute mapping configuration.

name Required

Type: string

The name of the attribute.

attribute Required

Type: string

The attribute value or reference.

myself

Type: array

The self properties for all modules within the STS Chain Template referenced in the STS Chain.

No Additional Items

Each item of this array must be:

Type: object

A property item for an STS Chain module. The final property name is determined by the index in the chain template (to fetch the UUID prefix) and the name of the property.

index Required

Type: integer

The index in the chain template of the property being set.

Value must be greater or equal to 0

name Required

Type: string

The name of the configuration property.

value Required

Type: array of string

The values of the configuration property.

No Additional Items

Each item of this array must be:

Type: string

partner

Type: array

The partner properties for all modules within the STS Chain Template referenced in the STS Chain.

No Additional Items

Each item of this array must be:

Type: object

A property item for an STS Chain module. The final property name is determined by the index in the chain template (to fetch the UUID prefix) and the name of the property.

Same definition as chains_items_properties_myself_items

Federations

Expand all Collapse all

Type: array

Configuration for federation providers and partners supporting SAML 2.0, OIDC, and WS-Federation protocols.

No Additional Items

Each item of this array must be:

Type: object

A federation configuration with protocol-specific settings and partners.

name Required

Type: string

A meaningful name to identify this federation.

protocol Required

Type: enum (of string)

The name of the protocol to be used in the federation.

Must be one of:

• "SAML2_0"
• "OIDC10"
• "WSFED"

role Required

Type: enum (of string)

The role of a federation. Use 'ip' for a SAML 2.0 identity provider federation, and 'sp' for a SAML 2.0 service provider federation. Use 'op' for an OpenID Connect Provider federation, and 'rp' for an OpenID Connect Relying Party federation.

Must be one of:

• "ip"
• "sp"
• "op"
• "rp"

template_name

Type: string

An identifier for the template on which to base this federation.

configuration

The protocol-specific configuration data. The contents will be different for each protocol and role combination.

One of

• OIDC Relying Party Configuration
• SAML 2.0 Identity Provider Configuration
• SAML 2.0 Service Provider Configuration
• WS-Federation Identity Provider Configuration
• WS-Federation Service Provider Configuration

OIDC Relying Party Configuration

Type: object

OIDC Relying Party configuration

redirect_uri_prefix Required

Type: stringFormat: uri

The reverse proxy address to prepend to the redirect URI sent to the provider to communicate with this instance. An example is 'https://www.reverse.proxy.com/mga'. For the value 'https://www.reverse.proxy.com/mga', the kickoff uri would be 'https://www.reverse.proxy.com/mga/sps/oidc/rp/<FEDERATION_NAME>/kickoff/<PARTNER_NAME>' and the redirect uri 'https://www.reverse.proxy.com/mga/sps/oidc/rp/<FEDERATION_NAME>/redirect/<PARTNER_NAME>'

response_types Required

Type: array of enum (of string)

List of response types which determine the flow to be executed. Valid values to be included are 'code', 'token', 'id_token'. This selects the default flow to run when a metadata URL is specified in the partner configuration.

Must contain a minimum of 1 items

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "code"
• "token"
• "id_token"

attribute_mappings

Type: object

The attribute mapping data.

name Required

Type: string

Name of the source.

source Required

Type: string

Attribute Source ID.

identity_mapping Required

Type: object

The identity mapping data.

active_delegate_id Required

Type: enum (of string)

The active mapping module instance. Valid values are skip-identity-map, default-map and default-http-custom-map.

Must be one of:

• "skip-identity-map"
• "default-map"
• "default-http-custom-map"

properties Required

Type: object

The mapping module specific properties. Use DefaultMappingProperties (ruletype, mappingrule) when activedelegateid is 'default-map'. Use CustomMappingProperties (appliesto, authtype, basicauthusername, basicauthpassword, clientkeystore, clientkeyalias, issueruri, messageformat, sslkeystore, uri) when activedelegateid is 'default-http-custom-map'.

rule_type

Type: enum (of string)

The type of the mapping rule. The only supported type currently is JAVASCRIPT.

Must be one of:

• "JAVASCRIPT"

mapping_rule

Type: string

A reference to an ID or name of a mapping rule.

applies_to

Type: string

Refers to STS chain that consumes call-out response. Required if WSTRUST message_format is specified, invalid otherwise.

auth_type

Type: enum (of string)

Authentication method used when contacting external service. Supported values are NONE, BASIC or CERTIFICATE

Must be one of:

• "NONE"
• "BASIC"
• "CERTIFICATE"

basic_auth_username

Type: string

Username for authentication to external service. Required if BASIC auth_type is specified, invalid otherwise.

basic_auth_password

Type: stringFormat: password

Password for authentication to external service. Required if BASIC auth_type is specified, invalid otherwise.

client_key_store

Type: string

Contains key for HTTPS client authentication. Required if CERTIFICATE auth_type is specified, invalid otherwise.

client_key_alias

Type: string

Alias of the key for HTTPS client authentication. Required if CERTIFICATE auth_type is specified, invalid otherwise.

issuer_uri

Type: string

Refers to STS chain that provides input for call-out request. Required if WSTRUST message_format is specified, invalid otherwise.

message_format

Type: enum (of string)

Message format of call-out request. Supported values are XML or WSTRUST.

Must be one of:

• "XML"
• "WSTRUST"

ssl_key_store

Type: string

SSL certificate trust store to use when validating SSL certificate of external service.

uri

Type: stringFormat: uri

Address of destination server to call out to.

advanced_configuration Required

Type: object

The advanced configuration data.

active_delegate_id Required

Type: enum (of string)

The active module instance.

Must be one of:

• "skip-advance-map"
• "default-map"

mapping_rule Required

Type: string

A reference to an ID or name of an advance configuration mapping rule.

rule_type Required

Type: enum (of string)

The type of the mapping rule.

Must be one of:

• "JAVASCRIPT"

SAML 2.0 Identity Provider Configuration

Type: object

SAML 2.0 Identity Provider configuration

access_policy

Type: string

The access policy that should be applied during single sign-on.

artifact_lifetime

Type: integer Default: 120

The number of seconds that an artifact is valid. The default value is 120. This setting is enabled only when HTTP artifact binding has been enabled.

Value must be greater or equal to 1

assertion_settings

Type: object

The assertion settings.

attribute_types

Type: array of string Default: ["*"]

Types of attributes to include in the assertion. An asterisk () indicates all attribute types. Default is [''].

No Additional Items

Each item of this array must be:

Type: string

session_not_on_or_after

Type: integer Default: 3600

Number of seconds that the security context should be discarded by the service provider.

Value must be greater or equal to 1

create_multiple_attribute_statements

Type: boolean

Whether to keep multiple attribute statements in the groups in which they were received.

valid_before

Type: integer Default: 60

Number of seconds before the issue date that an assertion is considered valid.

Value must be greater or equal to 0

valid_after

Type: integer Default: 60

Number of seconds the assertion is valid after being issued.

Value must be greater or equal to 1

artifact_resolution_services

Type: array

Endpoints where artifacts are exchanged for actual SAML messages. Required if artifact binding is enabled.

No Additional Items

Each item of this array must be:

Type: object

SAML Artifact Resolution Service endpoint configuration.

binding Required

Type: enum (of string)

Communication method used to transport SAML messages.

Must be one of:

• "soap"

default

Type: boolean Default: false

Whether this is the default endpoint.

index

Type: integer Default: 0

Reference to a particular endpoint.

Value must be greater or equal to 0

url

Type: stringFormat: uri

The URL of the endpoint. If not provided, automatically generated from point of contact URL.

attribute_mappings

Type: object

The attribute mapping data.

Same definition as attribute_mappings

company_name Required

Type: string

The name of the company that creates the identity provider or service provider.

encryption_settings

Type: object

The encryption and decryption configurations for SAML messages.

block_algorithm

Type: enum (of string) Default: "AES-128"

Block encryption algorithm used to encrypt and decrypt SAML messages.

Must be one of:

• "AES-128"
• "AES-192"
• "AES-256"
• "TRIPLEDES"

key_transport_algorithm

Type: enum (of string) Default: "RSA-OAEP"

Key transport algorithm used to encrypt and decrypt keys.

Must be one of:

• "RSA-v1.5"
• "RSA-OAEP"

key_identifier

Type: object

The certificate for encryption of outgoing SAML messages.

store Required

Type: string

The certificate database name.

label Required

Type: string

The certificate or key label.

decryption_key_identifier

Type: object

A public/private key pair for decrypting incoming messages.

Same definition as key_identifier

key_store Required

Type: string

The certificate database name.

key_alias Required

Type: string

The certificate or key label.

encrypt_name_id Required

Type: boolean

Whether the name identifiers should be encrypted.

encrypt_assertion Required

Type: boolean

Whether to encrypt assertions.

encrypt_assertion_attributes Required

Type: boolean

Whether to encrypt assertion attributes.

identity_mapping Required

Type: object

The identity mapping data.

Same definition as identity_mapping

extension_mapping Required

Type: object

The extension mapping data.

active_delegate_id Required

Type: enum (of string)

The active mapping module instance.

Must be one of:

• "skip-extension-map"
• "default-map"
• "federation-config"

mapping_rule Required

Type: string

A reference to an ID or name of an extension mapping rule.

manage_name_id_services

Type: array

Endpoints that accept SAML name ID management requests or responses.

No Additional Items

Each item of this array must be:

Type: object

Generic service endpoint configuration.

binding Required

Type: enum (of string)

Communication method used to transport SAML messages.

Must be one of:

• "artifact"
• "post"
• "redirect"
• "soap"

url

Type: stringFormat: uri

The URL of the endpoint. For non-SOAP bindings, automatically generated from point of contact URL.

message_valid_time

Type: integer Default: 300

The number of seconds that a message is valid. The default value is 300.

Value must be greater or equal to 1

message_issuer_format

Type: stringFormat: uri Default: "urn:oasis:names:tc:SAML:2.0:nameid-format:entity"

The format of the issuer of SAML message. The default value is 'urn:oasis:names:tc:SAML:2.0:nameid-format:entity'.

message_issuer_name_qualifier

Type: string

The name qualifier of the issuer of SAML messaged.

name_id_format

Type: object

The name identifier format configurations.

default

Type: string

The name identifier format to use when format attribute is not set or is unspecified.

supported

Type: array of string Default: ["urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"]

List of supported name identifier formats.

No Additional Items

Each item of this array must be:

Type: stringFormat: uri

need_consent_to_federate

Type: boolean Default: true

A setting that specifies whether to ask user's consent before linking the account. The default value is true.

exclude_session_index_in_single_logout_request

Type: boolean Default: false

A setting that specifies whether the LogoutRequest messages sent out from this entity will exclude SessionIndex during IP init SLO flow. The default value is false.

point_of_contact_url Required

Type: stringFormat: uri

The endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format is http[s]://hostname[:portnumber]/[junction]/sps.

provider_id

Type: string

A unique identifier that identifies the provider to its partner provider. If not provided or an empty string is provided, the default value is <point of contact URL>/<federation name>/saml20.

session_timeout

Type: integer Default: 7200

The number of seconds that the SAML session remains valid. The default value is 7200.

Value must be greater or equal to 1

signature_settings

Type: object

The signing and validation configurations for SAML messages and assertions.

signature_algorithm Required

Type: enum (of string) Default: "RSA-SHA256"

The signature algorithm to sign and validate SAML messages and assertions.

Must be one of:

• "RSA-SHA1"
• "RSA-SHA256"
• "RSA-SHA512"

digest_algorithm Required

Type: enum (of string)

The hash algorithm to apply to the transformed resources.

Must be one of:

• "SHA1"
• "SHA256"
• "SHA512"

signing_options

Type: object

Options for what to sign.

sign_assertion

Type: boolean Default: false

Whether to sign the assertion.

sign_authn_response

Type: boolean Default: false

Whether to sign the authentication responses.

sign_artifact_request

Type: boolean Default: false

Whether to sign the artifact request.

sign_artifact_response

Type: boolean Default: false

Whether to sign the artifact response.

sign_logout_request

Type: boolean Default: false

Whether to sign the logout request.

sign_logout_response

Type: boolean Default: false

Whether to sign the logout response.

sign_name_id_management_request

Type: boolean Default: false

Whether to sign the name ID management request.

sign_name_id_management_response

Type: boolean Default: false

Whether to sign the name ID management response.

validation_options

Type: object

Options for what to validate.

validate_authn_request

Type: boolean Default: false

Whether to validate the digital signature of an authentication request.

validate_assertion

Type: boolean Default: false

Whether to validate the digital signature of an assertion.

validate_artifact_request

Type: boolean

Whether to validate the digital signature of an artifact request.

validate_artifact_response

Type: boolean

Whether to validate the digital signature of an artifact response.

validate_logout_request

Type: boolean

Whether to validate the digital signature of a logout request.

validate_logout_response

Type: boolean

Whether to validate the digital signature of a logout response.

validate_name_id_management_request

Type: boolean

Whether to validate the digital signature of a name ID management request.

validate_name_id_management_response

Type: boolean

Whether to validate the digital signature of a name ID management response.

include_inclusive_namespaces

Type: boolean

Whether to include the InclusiveNamespaces element in the digital signature.

key_info_elements

Type: object

KeyInfo elements to include in the digital signature.

include_public_key

Type: boolean Default: false

Whether to include the public key in the KeyInfo element.

include_x509_certificate_data

Type: boolean Default: true

Whether to include the base64 encoded certificate data in the KeyInfo element.

include_x509_issuer_details

Type: boolean Default: false

Whether to include the issuer name and certificate serial number in the KeyInfo element.

include_x509_subject_key_identifier

Type: boolean Default: false

Whether to include the X.509 subject key identifier in the KeyInfo element.

include_x509_subject_name

Type: boolean Default: false

Whether to include the subject name in the KeyInfo element.

signing_key_identifier

Type: object

A public/private key pair for signing the SAML messages and assertions.

Same definition as key_identifier

validation_key_identifier

Type: object

The certificate to use to validate the signatures on incoming SAML assertions and messages.

Same definition as key_identifier

single_sign_on_service

Type: array

Endpoints at an Identity Provider that accept SAML authentication requests.

No Additional Items

Each item of this array must be:

Type: object

Single Sign-On service endpoint configuration.

binding Required

Type: enum (of string)

Communication method used to transport SAML messages.

Must be one of:

• "artifact"
• "post"
• "redirect"

url Required

Type: stringFormat: uri

The URL of the endpoint.

single_logout_service

Type: array

Endpoints that accept SAML logout requests or responses.

No Additional Items

Each item of this array must be:

Type: object

Generic service endpoint configuration.

Same definition as items_configuration_oneOf_i1_manage_name_id_services_items

alias_service_settings

Type: object

The alias service settings to store the user alias.

db_type Required

Type: enum (of string)

Whether the user's alias is stored in JDBC or LDAP.

Must be one of:

• "jdbc"
• "ldap"

ldap_connection

Type: string

The LDAP Connection to store the alias.

ldap_base_dn

Type: string

The LDAP BaseDN to search for the user.

SAML 2.0 Service Provider Configuration

Type: object

SAML 2.0 Service Provider configuration

artifact_lifetime

Type: integer Default: 120

The number of seconds that an artifact is valid. The default value is 120. This setting is enabled only when HTTP artifact binding has been enabled.

Value must be greater or equal to 1

assertion_consumer_services Required

Type: array

Endpoints at a Service Provider that receive SAML assertions.

No Additional Items

Each item of this array must be:

Type: object

SAML Assertion Consumer Service endpoint configuration.

binding Required

Type: enum (of string)

Communication method used to transport SAML messages.

Must be one of:

• "artifact"
• "post"
• "redirect"

default Required

Type: boolean

Whether this is the default endpoint.

index Required

Type: integer

Reference to a particular endpoint.

Value must be greater or equal to 0

url Required

Type: stringFormat: uri

The URL of the endpoint.

artifact_resolution_services Required

Type: array

Endpoints where artifacts are exchanged for actual SAML messages. Required if artifact binding is enabled.

No Additional Items

Each item of this array must be:

Type: object

SAML Artifact Resolution Service endpoint configuration.

Same definition as items_configuration_oneOf_i1_artifact_resolution_services_items

attribute_mappings

Type: object

The attribute mapping data.

Same definition as attribute_mappings

company_name Required

Type: string

The name of the company that creates the identity provider or service provider.

encryption_settings

Type: object

The encryption and decryption configurations for SAML messages.

Same definition as encryption_settings

identity_mapping Required

Type: object

The identity mapping data.

Same definition as identity_mapping

extension_mapping Required

Type: object

The extension mapping data.

Same definition as extension_mapping

authn_req_mapping Required

Type: object

The authentication request mapping data.

active_delegate_id Required

Type: enum (of string)

The active mapping module instance.

Must be one of:

• "skip-authn-request-map"
• "default-map"
• "federation-config"

mapping_rule Required

Type: string

A reference to an ID or name of an authentication request mapping rule.

manage_name_id_services

Type: array

Endpoints that accept SAML name ID management requests or responses.

No Additional Items

Each item of this array must be:

Type: object

Generic service endpoint configuration.

Same definition as items_configuration_oneOf_i1_manage_name_id_services_items

message_valid_time

Type: integer Default: 300

The number of seconds that a message is valid. The default value is 300.

Value must be greater or equal to 1

message_issuer_format

Type: stringFormat: uri Default: "urn:oasis:names:tc:SAML:2.0:nameid-format:entity"

The format of the issuer of SAML message. The default value is 'urn:oasis:names:tc:SAML:2.0:nameid-format:entity'.

message_issuer_name_qualifier

Type: string

The name qualifier of the issuer of SAML messaged.

name_id_format

Type: object

The name identifier format configurations.

Same definition as name_id_format

point_of_contact_url Required

Type: stringFormat: uri

The endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format is http[s]://hostname[:portnumber]/[junction]/sps.

provider_id

Type: string

A unique identifier that identifies the provider to its partner provider. If not provided or an empty string is provided, the default value is <point of contact URL>/<federation name>/saml20.

session_timeout

Type: integer Default: 7200

The number of seconds that the SAML session remains valid. The default value is 7200.

Value must be greater or equal to 1

signature_settings

Type: object

The signing and validation configurations for SAML messages and assertions.

Same definition as signature_settings

single_logout_service

Type: array

Endpoints that accept SAML logout requests or responses.

No Additional Items

Each item of this array must be:

Type: object

Generic service endpoint configuration.

Same definition as items_configuration_oneOf_i1_manage_name_id_services_items

alias_service_settings

Type: object

The alias service settings to store the user alias.

Same definition as alias_service_settings

WS-Federation Identity Provider Configuration

Type: object

WS-Federation Identity Provider configuration

assertion_settings

Type: object

The assertion settings.

Same definition as assertion_settings

company_name Required

Type: string

The name of the company that creates the identity provider or service provider.

identity_mapping Required

Type: object

The identity mapping data.

Same definition as identity_mapping

point_of_contact_url Required

Type: stringFormat: uri

The endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format is http[s]://hostname[:portnumber]/[junction]/sps.

WS-Federation Service Provider Configuration

Type: object

WS-Federation Service Provider configuration

company_name Required

Type: string

The name of the company that creates the identity provider or service provider.

identity_mapping Required

Type: object

The identity mapping data.

Same definition as identity_mapping

point_of_contact_url Required

Type: stringFormat: uri

The endpoint URL of the point of contact server. The point of contact server is a reverse proxy server that is configured in front of the runtime listening interfaces. The format is http[s]://hostname[:portnumber]/[junction]/sps.

replay_validation Required

Type: boolean

Whether to enable one-time assertion use enforcement.

partners

Type: array

List of federation partners to create for this federation.

No Additional Items

Each item of this array must be:

One of

• OIDC Relying Party Partner Configuration
• SAML 2.0 Identity Provider Partner Configuration
• SAML 2.0 Service Provider Partner Configuration
• WS-Federation Identity Provider Partner Configuration
• WS-Federation Service Provider Partner Configuration

OIDC Relying Party Partner Configuration

Type: object

OIDC Relying Party partner

name Required

Type: string

Name of the OIDC Relying Party partner.

client_id Required

Type: string

The ID that identifies this client to the provider.

client_secret

Type: stringFormat: password

The secret associated with the client ID. Do not include if creating a public client.

basic_configuration Required

Type: object

The basic configuration data.

active_delegate_id Required

Type: enum (of string)

The active module instance.

Must be one of:

• "noMetadata"
• "metadataEndpointUrl"

metadata_endpoint_url

Type: stringFormat: uri

The /metadata endpoint URL of the provider. Only valid if activedelegateid is 'metadataEndpointUrl'.

issuer_identifier

Type: string

The issuer 'iss' value of the provider. Only valid if activedelegateid is 'noMetadata'.

response_types

Type: array of enum (of string)

List of response types which determines which flow to be executed. Only valid if activedelegateid is 'noMetadata'.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "code"
• "token"
• "id_token"

authorization_endpoint_url

Type: stringFormat: uri

The /authorize endpoint URL of the provider. Only valid if activedelegateid is 'noMetadata'.

token_endpoint_url

Type: stringFormat: uri

The /token endpoint URL of the provider. Required if 'code' response type is selected. Only valid if activedelegateid is 'noMetadata'.

user_info_endpoint_url

Type: stringFormat: uri

The /userinfo endpoint URL of the provider. Only valid if activedelegateid is 'noMetadata'.

signature_algorithm

Type: enum (of string)

The signing algorithm to use.

Must be one of:

• "none"
• "HS256"
• "HS384"
• "HS512"
• "RS256"
• "RS384"
• "RS512"
• "ES256"
• "ES384"
• "ES512"
• "PS256"
• "PS384"
• "PS512"

verification_keystore

Type: string

When signature algorithm requires a certificate, the keystore which contains the selected certificate to perform the signing.

verification_key_alias

Type: string

When signature algorithm requires a certificate, the alias of the public key in the selected keystore to use in signature verification.

jwks_endpoint_url

Type: stringFormat: uri

When signature algorithm requires a certificate, the JWK endpoint of the provider. If a metadata endpoint is specified in BasicConfigurationData, the JWK URL will be read from metadata information. Cannot be specified if using a signingKeyLabel.

key_management_algorithm

Type: enum (of string)

The key management algorithm to use.

Must be one of:

• "none"
• "dir"
• "A128KW"
• "A192KW"
• "A256KW"
• "A128GCMKW"
• "A192GCMKW"
• "A256GCMKW"
• "ECDH-ES"
• "ECDH-ES+A128KW"
• "ECDH-ES+A192KW"
• "ECDH-ES+A256KW"
• "RSA1_5"
• "RSA-OAEP"
• "RSA-OAEP-256"

content_encryption_algorithm

Type: enum (of string)

The content encryption algorithm to use.

Must be one of:

• "none"
• "A128CBC-HS256"
• "A192CBC-HS384"
• "A256CBC-HS512"
• "A128GCM"
• "A192GCM"
• "A256GCM"

decryption_keystore

Type: string

When key management algorithm requires a certificate, the keystore which contains the selected certificate to perform JWT decryption.

decryption_key_alias

Type: string

When key management algorithm requires a certificate, the alias of the private key in the selected keystore to perform JWT decryption.

scope

Type: array of string Default: ["openid"]

An array of strings that identify the scopes to request from the provider. Defaults to ['openid'].

No Additional Items

Each item of this array must be:

Type: string

perform_user_info

Type: boolean

A setting that specifies whether to perform user info request automatically whenever possible.

token_endpoint_auth_method Required

Type: enum (of string)

The token endpoint authentication method.

Must be one of:

• "client_secret_basic"
• "client_secret_post"

attribute_mappings

Type: object

The attribute mapping data.

Same definition as attribute_mappings

identity_mapping

Type: object

The identity mapping data.

Same definition as identity_mapping

advance_configuration

Type: object

The advance configuration data.

Same definition as advanced_configuration

SAML 2.0 Identity Provider Partner Configuration

Type: object

SAML 2.0 Identity Provider partner

name Required

Type: string

Name of the federation partner.

enabled

Type: boolean Default: true

Whether this partner is enabled.

role

Type: enum (of string) Default: "ip"

The role of the partner.

Must be one of:

• "ip"

template_name

Type: string

An identifier for the template on which to base this partner.

access_policy

Type: string

The access policy that should be applied during single sign-on.

artifact_resolution_services

Type: object

Partner's endpoints where artifacts are exchanged for actual SAML messages. Required if artifact binding is enabled.

Same definition as items_configuration_oneOf_i1_artifact_resolution_services_items

assertion_consumer_services Required

Type: array

Partner's endpoints that receive SAML assertions.

No Additional Items

Each item of this array must be:

Type: object

SAML Assertion Consumer Service endpoint configuration.

Same definition as items_configuration_oneOf_i2_assertion_consumer_services_items

assertion_settings Required

Type: object

The assertion settings.

Same definition as assertion_settings

attribute_mappings

Type: object

The attribute mapping data.

Same definition as attribute_mappings

encryption_settings

Type: object

The encryption and decryption configurations for SAML messages.

Same definition as encryption_settings

identity_mapping

Type: object

The identity mapping data.

Same definition as identity_mapping

extension_mapping Required

Type: object

The extension mapping data.

Same definition as extension_mapping

include_fed_id_in_alias_partner_id

Type: boolean Default: false

A setting that specifies whether to append federation ID to partner ID when mapping user aliases. The default value is false.

logout_request_lifetime

Type: integer Default: 120

A setting that specifies Logout request lifetime in number of seconds. If not provided, the default value is 120.

Value must be greater or equal to 1

manage_name_id_services

Type: array

Partner's endpoints that accept SAML name ID management requests or responses.

No Additional Items

Each item of this array must be:

Type: object

Generic service endpoint configuration.

Same definition as items_configuration_oneOf_i1_manage_name_id_services_items

name_id_format

Type: object

The name identifier format configurations.

Same definition as name_id_format

provider_id Required

Type: string

A unique identifier that identifies the partner.

signature_settings

Type: object

The signing and validation configurations for SAML messages and assertions.

Same definition as signature_settings

single_logout_service

Type: object

Partner's endpoints that accept SAML logout requests or responses.

Same definition as items_configuration_oneOf_i1_manage_name_id_services_items

soap_settings

Type: object

A setting that specifies the connection parameters for the SOAP endpoints.

server_cert_validation Required

Type: object

Server certificate validation configuration.

store Required

Type: string

The certificate database name.

label

Type: string

The certificate label. If not provided, all certificates in the database will be trusted.

client_auth_data Required

Type: object

Client authentication configuration.

method Required

Type: enum (of string)

The authentication method.

Must be one of:

• "ba"
• "cert"
• "none"

basic_auth_username

Type: string

The basic authentication username.

basic_auth_password

Type: stringFormat: password

The basic authentication password.

client_key_store

Type: string

The certificate database name.

client_key_alias

Type: string

The personal certificate label.

SAML 2.0 Service Provider Partner Configuration

Type: object

SAML 2.0 Service Provider partner

name Required

Type: string

Name of the federation partner.

enabled

Type: boolean Default: true

Whether this partner is enabled.

role

Type: enum (of string) Default: "sp"

The role of the partner.

Must be one of:

• "sp"

template_name

Type: string

An identifier for the template on which to base this partner.

anonymous_user_name

Type: string

This is a one-time name identifier that allows a user to access a service through an anonymous identity. The user name entered here is one that the service provider will recognize as a one-time name identifier for a legitimate user in the local user registry.

artifact_resolution_services

Type: object

Partner's endpoints where artifacts are exchanged for actual SAML messages. Required if artifact binding is enabled.

Same definition as items_configuration_oneOf_i1_artifact_resolution_services_items

assertion_settings

Type: object

The assertion settings.

Same definition as assertion_settings

attribute_mappings

Type: object

The attribute mapping data.

Same definition as attribute_mappings

encryption_settings

Type: object

The encryption and decryption configurations for SAML messages.

Same definition as encryption_settings

force_authn_to_federate

Type: boolean

A setting that specifies whether to force user to authenticate before linking the account.

identity_mapping

Type: object

The identity mapping data.

Same definition as identity_mapping

extension_mapping

Type: object

The extension mapping data.

Same definition as extension_mapping

authn_req_mapping Required

Type: object

The authentication request mapping data.

Same definition as authn_req_mapping

include_fed_id_in_alias_partner_id

Type: boolean

A setting that specifies whether to append federation ID to partner ID when mapping user aliases.

manage_name_id_services

Type: array

Partner's endpoints that accept SAML name ID management requests or responses.

No Additional Items

Each item of this array must be:

Type: object

Generic service endpoint configuration.

Same definition as items_configuration_oneOf_i1_manage_name_id_services_items

map_unknown_aliases

Type: boolean

A setting that specifies whether to map non-linked persistent name ID to one-time username.

name_id_format

Type: object

The name identifier format configurations.

Same definition as name_id_format

provider_id Required

Type: string

A unique identifier that identifies the partner.

signature_settings

Type: object

The signing and validation configurations for SAML messages and assertions.

Same definition as signature_settings

single_logout_service

Type: array

Partner's endpoints that accept SAML logout requests or responses.

No Additional Items

Each item of this array must be:

Type: object

Generic service endpoint configuration.

Same definition as items_configuration_oneOf_i1_manage_name_id_services_items

single_sign_on_service

Type: array

Partner's endpoints that accept SAML authentication requests.

No Additional Items

Each item of this array must be:

Type: object

Single Sign-On service endpoint configuration.

Same definition as items_configuration_oneOf_i1_single_sign_on_service_items

soap_settings

Type: object

A setting that specifies the connection parameters for the SOAP endpoints.

Same definition as soap_settings

default_target_url

Type: stringFormat: uri

Default URL where end-user will be redirected after the completion of single sign-on.

WS-Federation Identity Provider Partner Configuration

Type: object

WS-Federation Identity Provider partner

name Required

Type: string

Name of the federation partner.

enabled

Type: boolean Default: true

Whether this partner is enabled.

role

Type: enum (of string) Default: "ip"

The role of the partner.

Must be one of:

• "ip"

template_name

Type: string

An identifier for the template on which to base this partner.

attribute_types

Type: array of string Default: ["*"]

Specifies the types of attributes to include in the assertion. The default, an asterisk (*), includes all the attribute types that are specified in the identity mapping file.

No Additional Items

Each item of this array must be:

Type: string

endpoint Required

Type: stringFormat: uri

The endpoint of the WS-Federation partner.

identity_mapping Required

Type: object

The identity mapping data.

Same definition as identity_mapping

include_certificate_data

Type: boolean Default: true

Whether to include the BASE64 encoded certificate data with the signature. Defaults to true if not specified.

include_issuer_details

Type: boolean Default: false

Whether to include the issuer name and the certificate serial number with the signature. Defaults to false if not specified.

include_public_key

Type: boolean Default: false

Whether to include the public key with the signature. Defaults to false if not specified.

include_subject_key_identifier

Type: boolean Default: false

Whether to include the X.509 subject key identifier with the signature. Defaults to false if not specified.

include_subject_name

Type: boolean Default: false

Whether to include the subject name with the signature. Defaults to false if not specified.

max_request_lifetime Required

Type: integer

The amount of time that the request is valid (in milliseconds).

Value must be greater or equal to 1

realm Required

Type: string

The realm of the WS-Federation partner.

signature_algorithm

Type: enum (of string)

The signature algorithm to use for signing SAML assertions. Only required if signsamlassertion is set to true.

Must be one of:

• "RSA-SHA1"
• "RSA-SHA256"
• "RSA-SHA512"

signing_key_identifier

Type: object

The certificate to use for signing the SAML assertions. Only required if signsamlassertion is set to true.

Same definition as key_identifier

sign_saml_assertion

Type: boolean

Whether or not the assertion needs to be signed.

subject_confirmation_method

Type: enum (of string)

The subject confirmation method.

Must be one of:

• "No Subject Confirmation Method"
• "urn:oasis:names:tc:SAML:1.0:cm:bearer"
• "urn:oasis:names:tc:SAML:1.0:cm:holder-of-key"
• "urn:oasis:names:tc:SAML:1.0:cm:sender-vouches"

use_inclusive_namespace

Type: boolean Default: true

Whether or not to use the InclusiveNamespaces construct. Defaults to true if not specified.

WS-Federation Service Provider Partner Configuration

Type: object

WS-Federation Service Provider partner

name Required

Type: string

Name of the federation partner.

enabled

Type: boolean Default: true

Whether this partner is enabled.

role

Type: enum (of string) Default: "sp"

The role of the partner.

Must be one of:

• "sp"

template_name

Type: string

An identifier for the template on which to base this partner.

endpoint Required

Type: stringFormat: uri

The endpoint of the WS-Federation partner.

identity_mapping Required

Type: object

The identity mapping data.

Same definition as identity_mapping

key_alias

Type: object

The keystore and certificate to use to validate the signature. Only required if verifysignatures is set to true and usekey_info is set to false.

Same definition as key_identifier

key_info

Type: string

The regular expression used to find the X509 certificate for signature validation. Only required if verifysignatures is set to true and usekey_info is set to true.

max_request_lifetime Required

Type: integer

The amount of time that the request is valid (in milliseconds).

Value must be greater or equal to 1

realm Required

Type: string

The realm of the WS-Federation partner.

use_key_info

Type: boolean

Whether to use the keyInfo of the XML signature to find the X509 certificate for signature validation (true) or the specified keyalias (false). Only required if verifysignatures is set to true.

verify_signatures

Type: boolean Default: false

Whether to enable signature validation. Defaults to false if not specified.

want_multiple_attribute_statements Required

Type: boolean

Whether to create multiple attribute statements in the Universal User.

import_partners

Type: array

List of XML metadata documents which define partners for a configured Federation.

No Additional Items

Each item of this array must be:

Type: object

A partner to import from XML metadata.

name Required

Type: string

Name of the federation partner to create.

metadata Required

Type: string

Path to XML metadata file which contains the partner's configuration properties.

export_metadata

Type: string

Optional path to file to write Federation's XML metadata file to. eg: 'idpmetadata.xml'

Example:

federations:
- name: saml20idp
  protocol: SAML2_0
  role: ip
  export_metadata: idpmetadata.xml
  configuration:
    company_name: IdP Company
    point_of_contact_url: https://www.myidp.ibm.com/isam
    assertion_settings:
      valid_before: 300
      valid_after: 300
    need_consent_to_federate: false
    signature_settings:
      validation_options:
        validate_authn_request: true
      signing_options:
        sign_authn_response: true
        sign_logout_request: true
        sign_logout_response: true
        signing_key_identifier:
          store: myidpkeys
          label: CN=idp,OU=Security,O=IBM,C=AU
      key_info_elements:
        include_x509_certificate_data: true
        include_x509_subject_name: false
        include_x509_subject_key_identifier: false
        include_x509_issuer_details: false
        include_public_key: false
    identity_mapping:
      active_delegate_id: default-map
      properties:
        mapping_rule: ip_saml20
    extension_mapping:
      active_delegate_id: skip-extension-map
    name_id_format:
      default: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    single_sign_on_service:
    - binding: post
    - binding: redirect
    exclude_session_index_in_single_logout_request: false
    single_logout_service:
    - binding: post
    - binding: redirect
    encryption_settings:
      decryption_key_identifier:
        store: myidpkeys
        label: CN=idp,OU=Security,O=IBM,C=AU
    message_valid_time: 300
    session_timeout: 7200

Advanced Configuration Parameters

To set Advanced Configuration Properties, see the entry in the Appliance or Container documentation.

HTTP Template Files

To upload HTTP template files, see the entry in the Appliance or Container documentation.

JavaScript Mapping Rules

To upload JavaScript mapping rules, see the entry in the Appliance or Container documentation.

Server Connections

To configure third party Server Connections, see the entry in the Appliance or Container documentation.

Runtime Server Configuration

To set Runtime Server properties, see the entry in the Appliance or Container documentation.