Federation - SAML / WebSSO
Here, you can specify general settings for SAML federations
Federations
SAML Configuration
This is kept in the root of the federations JSON object.
Max Time Difference
Maximum acceptable time difference in minutes - allows for clock skew between issuer and service provider.
Default: 2
JSON key is websso.samlsigning.maxtimedifference.minutes
Authentication Methods
List separated by semicolon - list of names to use for authention methods in SAML document - e.g. 6=LDAP;42=NemID;43=SMS OTP
- If not mapped to another name, the value for authmethod attribute/claim is the plugin ID of the authentication method used to authenticate the user.
Default: None
JSON key is websso.samlsigning.maxtimedifference.minutes
HTTP Proxy configuration
This is kept in a JSON object called proxy. Note that this configuration is shared with the OpenID Connect / JWT Federation configuration.
Enabled
Check to enable HTTP proxy.
Default: false
JSON key is enabled
Hostname
Maximum acceptable time difference in minutes - allows for clock skew between issuer and service provider.
Default: 2
JSON key is host
Port
TCP Port number of proxy server
Default: 8080
JSON key is port
Userid
Userid to authenticate to proxy server.
Default: None
JSON key is user
Password
Password needed to authenticate to proxy server - can be encrypted, see Encrypting or Obfuscating Passwords
Default: None
JSON key is password
No Proxy For
Hostname matching this pattern will not be proxied
Default: None
JSON key is noproxyfor
SAML Service Providers
SAML / WebSSO Service Provider configuration
This is kept in the federation root as a JSON array called saml.serviceproviders.
Service Providers
SAML / WebSSO Service Providers - any service provider you wish to issue SAML tickets to should be configured here.
Default: None
JSON key is saml.serviceproviders - each service provider is a separate JSON object within this array.
SAML / WebSSO Service Provider
Each SAML Service provider is a separate JSON object within the JSON Array saml.serviceproviders
SAML / WebSSO Service Provider
Name
Unique name of SAML Service Provider - this is the name that this provider is known under as referenced from Ceptor Gateway in the SAML/ADFS/WebSSO Authentication section -see the property "Service Provider Name"
Default: None
JSON key is name
Display Name
Display name - this name can be used in presentation to users if they need to choose between providers.
Default: None
JSON key is display.name
Description
Here, you can enter a description of the service provider - the description itself is not actively used anywhere, so it is just for informational purposes.
Default: None
JSON key is description
URL
Service Provider URL - this is the URL that the login response ticket is sent to.
Default: None
JSON key is url
Issuer
Issuer name - this name is seen by the Service Provider as the issuer of the SAML ticket.
Default: Ceptor
JSON key is issuer
Audience
Audience - if not set, defaults to URL. This will be added as audience in the SAML Response ticket.
Default: URL
JSON key is audience
Identifiers
List of valid identifiers for this service provider.
When a SAML Request is received, it contains an issuer - this issuer is matched up against the defined identifiers, and the first configured service provider that matches, if any is picked. Note that multiple identifiers can be configured.
Default: None
JSON key is identifiers (containing a JSON Array of strings)
Role Pattern
When adding the role/groups attribute to a SAML ticket, only groups matching this pattern will be included.
Refer to description of wildcards/regex patterns here: Locations - Conditions
Default: *
JSON key is role.pattern
Attributes
Attributes to send as claims to Service Provider.
See SAML / JWT Attributes / Claims for information of content.
Default: None
JSON key is attributes - must be a JSON Array of Strings, each in format name=value
IDP Metadata Template
This contains the template for federation metadata.
In this template, you can define the SAML 2.0 Identity Provider Metadata Template - see here: Ceptor Gateway - Authentication - SAML/ADFS/WebSSO how to retrieve this metadata at runtime - using this template make it possible to provide an URL where the service provider can periodically retrieve the SAML Identity Provider Federation metadata from.
This metadata contains information about certificates needed to verify the signature, the macros %{signcert} and %{encryptcert} are replaced with the actual certificates loaded from the keystores.
Do not forget to adjust the information within to match your scenario.
You can find all the details you never wanted to know about federation metadata here: https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf or a simplified overview here: https://www.oasis-open.org/committees/download.php/51890/SAML%20MD%20simplified%20overview.pdf
For most integrations, the example will be enough for the Service Provider to retrieve fields he needs, mainly the certificates.
Default: None
JSON key is identityprovider.metadata
SAML Response Script
In order to be able to modify all aspects of a SAML response before it is signed, it is possible to specify a SAML Response script that is executed immediately after generating the SAML response string, but before it is signed.
It can optionally return a modified string containing a customized SAML response, which will then be signed and returned.
The documentation in Ceptor Console when editing the script contains an example script written in Groovy that adds an additional Attribute to the SAML response before it is signed.
When the script is called, it has these variables available:
- samlversion - 1 or 2 depending on which SAML type response is being generated
- context - Script context, with additional attributes about the user context available - see below
- input - SAML Response about to be created - can be modified and returned.
The context looks like the following:
public class ScriptContext { /** Session Controller */ public PTSServer sessionController; /** Configuration for session controller and authentication plugins */ public Properties configuration; /** Session we are generating SAML responses for */ public User session; /** SAML request as string, or null if no request present */ public String samlRequest; /** Parsed SAML Request, or null if not present */ public ADFSSamlRequest parsedSaml; /** Service Provider entry */ public ADFSSamlSSOAuthPlugin.ServiceProviderEntry sp; }
The context.parsedSaml attribute above has these values available:
public static class ADFSSamlRequest { public boolean saml2; public String issueInstant; public String requestID; // SAML 2 public String issuer; public String destination; }
Default: None
JSON key is saml.response.script
Keystore
The keystore is configured in a JSON object called keystore within the service provider's JSON object.
Key or certificate configuration
JCE Provider
Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.
Default: None
JSON key is provider
Keystore type
Keystore type, usually PKCS12 or JKS
Default: PKCS12
JSON key is type
Filename
Name of file to load keystore from - note that some keystores, e.g. Luna does not have a file
Default: None
JSON key is file
Password
Password for the keystore - can be encrypted, see Encrypting or Obfuscating Passwords
Default: None
JSON key is password
Password per alias
This is only needed if you have specific aliases in your keystore which have passwords that differ from the main keystore password - it allows you to specify a password for each alias specifically.
Default: None
JSON key is password.per.alias - this is a JSON Array with the format alias=password
Alias of private key
If provided, only the private key with the specified alias will be loaded.
Default: None
JSON key is alias.privkey
Alias of certificate
If provided, only the certificate with the specified alias will be loaded
Default: None
JSON key is alias.cert
Private key
Allows you to provide the private key as an RSA key in PKCS#8 format by pasting it directly.
Default: None
JSON key is privatekey
Certificate
Allows you to provide the certificate as Base64 encoded DER by pasting it directly instead of loading it from a keystore.
Default: None
JSON key is certificate
See also Keystore configuration for additional details of configuring keystores when using federation.
SAML Identity Providers
SAML / WebSSO Identity Provider configuration
This is kept in the federation root as a JSON array called saml.identityproviders.
Identity Providers
SAML / WebSSO Identity Providers - any identity provider you wish to be able to receive SAML Reponses from must be configured here.
Default: None
JSON key is saml.identityproviders - each identity provider is a separate JSON object within this array.
SAML / WebSSO Identity Provider
Name
Unique name of SAML Identity Provider.
This is the name that this provider is known under as referenced from Ceptor Gateway in the SAML/ADFS/WebSSO Authentication section -see the property "Identity Provider Name"
Default: None
JSON key is name
Display Name
Display name - this name can be used in presentation to users if they need to choose between providers.
Default: None
JSON key is display.name
Description
Here, you can enter a description of the identity provider - the description itself is not actively used anywhere, so it is just for informational purposes.
Default: None
JSON key is description
SAML Identifier
Enter SAML Identifier - defaults to Identity Provider Name if not entered.
This identifier is used in the wtrealm=
parameter when redirecting to the identity provider to sign in.
Default: Identity Provider Name
JSON key is identifier
Audience
If specified, the audience in the received SAML response must match this pattern - wildcards can be used, and if not set, audience validation is not done.
Default: None
JSON key is expected.audience.pattern
Use subject as userid
If true, subject from SAML response, if present, is used as userid.
Default: None
JSON key is subject.as.userid
Userid Attribute Name
Semicolon separated list of attribute names - the first match will be used as userid if such an attribute is provided in the SAML response.
Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn;upn
JSON key is userid.attribute.name
Username Attribute Name
Semicolon separated list of attribute names - the first match will be used as username if such an attribute is provided in the SAML response.
Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name;name
JSON key is username.attribute.name
Role Attribute Name
Semicolon separated list of attribute names - the first match will be used as user groups if such an attribute is provided in the SAML response.
Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role;role
JSON key is role.attribute.name
Role Pattern
Provided user groups must match this pattern, or they are ignored.
Default: None
JSON key is role.pattern
Attributes to store
Pattern for deciding which attributes to copy from the SAML response into the session.
Default: *
JSON key is attributes.to.store.in.session
URL
URL to identity provider.
If Ceptor Gateway redirects the user to the identity provider to ask for signin, it will use this URL, but add these query parameters to it:?wa=wsignin1.0&id=passive&wtrealm=<SAML identifier>&wreply=<Return URL>&wct=<Timestamp>
Default: None
JSON key is url
Known IPs
List of known IP adresses (separate with semicolon). This list can be used by applications or gateway to automatically redirect to specific Identity Providers if the client uses a matching IP address.
Default: None
JSON key is known.ip.list
Metadata URL
SAML2 Identity Provider Federation Metadata - if specified, it is retrieved online from the Identity Provider - the keys/certificates present in the metadata will be used for validating the SAML response instead of having to configure certificates manually.
Default: None
JSON key is metadata.url
Metadata update interval
Number of minutes between refreshing the metadata from the metdata URL if specified.
Default: 120
JSON key is metadata.update.interval.minutes
Metadata
If metadata cannot be retrieved from online, it can instead be pasted here.
Default: None
JSON key is metadata
SP Metadata Template
Template for providing Service Provider Metadata to Identity Provider.
%{signcert} will be replaced with the signing certificate, and %{encryptcert} will be replaced with the encryption certificate.
The encryption certificate is optionally loaded from the Keystore configuration.
Default: None
JSON key is serviceprovider.metadata
SAML Request Template
This is a template for how the generated SAML Request should look - remember to modify URLs to match your scenario.
Default: None
JSON key is samlrequest
Keystore
The keystore is configured in a JSON object called keystore within the identity provider's JSON object.
Key or certificate configuration
JCE Provider
Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.
Default: None
JSON key is provider
Keystore type
Keystore type, usually PKCS12 or JKS
Default: PKCS12
JSON key is type
Filename
Name of file to load keystore from - note that some keystores, e.g. Luna does not have a file
Default: None
JSON key is file
Password
Password for the keystore - can be encrypted, see Encrypting or Obfuscating Passwords
Default: None
JSON key is password
Password per alias
This is only needed if you have specific aliases in your keystore which have passwords that differ from the main keystore password - it allows you to specify a password for each alias specifically.
Default: None
JSON key is password.per.alias - this is a JSON Array with the format alias=password
Alias of private key
If provided, only the private key with the specified alias will be loaded.
Default: None
JSON key is alias.privkey
Alias of certificate
If provided, only the certificate with the specified alias will be loaded
Default: None
JSON key is alias.cert
Private key
Allows you to provide the private key as an RSA key in PKCS#8 format by pasting it directly.
Default: None
JSON key is privatekey
Certificate
Allows you to provide the certificate as Base64 encoded DER by pasting it directly instead of loading it from a keystore.
Default: None
JSON key is certificate
See also Keystore configuration for additional details of configuring keystores when using federation.
Signer Certificates
This configuration is stored in the JSON Object signer.certificates inside the identity provider JSON.
Additional Signer Certificates
JCE Provider
Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.
Default: None
JSON key is provider
Certificates
Provide a list of filenames or certificates directly within the configuration.
This allows you to specify additional trusted signer certificates for use when validating signed SAML Response - note that if you already are loading federation metadata from online, or have it pasted, these certificates configured here are in addition to the ones from the metadata.
Default: None
JSON key is certificates - which is a JSON Array of strings, each containing a filename of a certificate in .cer (binary or base64 encoded), .der or .p7b format or the certificate itself, if starting with -----BEGIN CERTIFICATE-----
See also Keystore configuration for additional details of configuring keystores when using federation.
Encryption Certificate
This configuration is stored in the JSON Object encryption.certificates inside the identity provider JSON.
Encryption Certificate
JCE Provider
Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.
Default: None
JSON key is provider
Certificates
If you wish to specify an encryption certificate for use when encrypting a SAML request, you can do so here - normally you would use federation metadata for this, but it can be specified manually.
Default: None
JSON key is certificate
SSL
This configuration is stored in the JSON Object ssl inside the identity provider JSON.
SSL/TLS related configuration when loading metadata
Verify server SSL certificate
Uncheck to disable SSL server certificate validation - if checked, SSL server certificates must either match installed root certificates in the JVM, or one of the additionally specified certificates.
Default: true
JSON key is verify.server.cert
Verify server SSL hostname
Uncheck to disable SSL hostname verification - if checked, the SSL hostname is matched up against the SSL server certificate.
Default: true
JSON key is verify.hostname
JCE Provider
Name of JCE provider - if left blank, platform default is used. Can be set to e.g. Luna to support hardware crypto providers assuming Luna JCE provider is installed.
Default: None
JSON key is provider - inside accepted.certificates JSON object within the ssl object.
Certificates
Provide a list of filenames or certificates directly within the configuration.
This allows you to specify additional SSL server issuer trust certificates certificates for use when validating signed SSL server certificate when retrieving metadata from remote
Default: None
JSON key is certificates- inside accepted.certificates JSON object within the ssl object.
© Ceptor ApS. All Rights Reserved.