libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

saml general config

Browse source
This commit is contained in:
Bill Burke 2016-06-02 16:50:43 -04:00
parent 8cd0ce78d1
commit 5c99a41b66
11 changed files with 142 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
topics/saml/java/general-config.adoc
View file

@ -2,7 +2,7 @@
==== General Adapter Config
Each SAML adapter supported by Keycloak can be configured by a simple XML text file.
Each SAML client adapter supported by {{book.project.name}} can be configured by a simple XML text file.
This is what one might look like:
[source,xml]
@ -52,7 +52,7 @@ This is what one might look like:
----
Some of these configuration switches may be adapter specific and some are common across all adapters.
For Java adapters you can use `${...}` enclosure as System property replacement.
For example `${jboss.server.config.dir}`.
For Java adapters you can use `$\{...}` enclosure as System property replacement.
For example `$\{jboss.server.config.dir}`.

24
topics/saml/java/general-config/idp_element.adoc
View file

@ -1,7 +1,7 @@
===== IDP Element
Everything in the IDP element describes the settings for the IDP the SP is communicating with.
Everything in the IDP element describes the settings for the identity provider (authentication server) the SP is communicating with.
[source,xml]
----
@ -12,19 +12,23 @@ Everything in the IDP element describes the settings for the IDP the SP is commu
...
</IDP>
----
Here are the attribute config options you can specify within the `IDP` element declaration.
entityID::
This is the issuer ID of the IDP. _REQUIRED._.
This is the issuer ID of the IDP. This setting is _REQUIRED._.
signaturesRequired::
If set to true, the client adapter will sign every document it sends to the IDP.
Also, the client will expect that the IDP will be signing an documents sent to it.
This switch sets the default for all request and response types, but you will see later that you have some fine grain control over this. _OPTIONAL._
If set to `true`, the client adapter will sign every document it sends to the IDP.
Also, the client will expect that the IDP will be signing any documents sent to it.
This switch sets the default for all request and response types, but you will see later that you have some fine grain control over this.
This setting is _OPTIONAL_ and will default to `false`.
signatureAlgorithm::
This is the signature algorithm that the IDP expects signed documents to use _OPTIONAL._.
The default value is RSA_SHA256, but you can also use RSA_SHA1, RSA_256, RSA_512, and DSA_SHA1.
This is the signature algorithm that the IDP expects signed documents to use.
Allowed values are: `RSA_SHA1`, `RSA_SHA256`, `RSA_SHA512`, and `DSA_SHA1`.
This setting is _OPTIONAL_
and defaults to `RSA_SHA256`.
signatureCanonicalizationMethod::
This is the signature canonicalization method that the IDP expects signed documents to use _OPTIONAL._.
This is the signature canonicalization method that the IDP expects signed documents to use. This setting is _OPTIONAL._.
The default value is `http://www.w3.org/2001/10/xml-exc-c14n#` and should be good for most IDPs.

16
topics/saml/java/general-config/idp_keys_subelement.adoc
View file

@ -2,5 +2,19 @@
===== IDP Keys subelement
The Keys sub element of IDP is only used to define the certificate or public key to use to verify documents signed by the IDP.
It is defined in the same way as the <<_sp_keys,SP's Key's element>>.
It is defined in the same way as the <<fake/../../../../saml/java/general-cnfig/sp-keys.adoc#_saml-sp-keys,SP's Key's element>>.
But again, you only have to define one certificate or public key reference.
[source,xml]
----
<IDP entityID="idp">
...
<Keys>
<Key signing="true">
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<Certificate alias="demo"/>
</KeyStore>
</Key>
</Keys>
</IDP>
----

23
topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc
View file

@ -1,7 +1,8 @@
===== IDP SingleLogoutService sub element
The `SingleLogoutService` sub element defines the logout SAML endpoint of the IDP.
The `SingleLogoutService` sub element defines the logout SAML endpoint of the IDP. The client adapter will send requests
to the IDP formatted via the settings within this element when it wants to logout.
[source,xml]
----
@ -16,31 +17,31 @@ The `SingleLogoutService` sub element defines the logout SAML endpoint of the ID
----
signRequest::
Should the client sign logout requests it makes to the IDP? _OPTIONAL._.
Should the client sign logout requests it makes to the IDP? This setting _OPTIONAL._.
Defaults to whatever the IDP `signaturesRequired` element value is.
signResponse::
Should the client sign logout responses it sends to the IDP requests? _OPTIONAL._.
Should the client sign logout responses it sends to the IDP requests? This setting _OPTIONAL._.
Defaults to whatever the IDP `signaturesRequired` element value is.
validateRequestSignature::
Should the client expect signed logout request documents from the IDP? _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
Should the client expect signed logout request documents from the IDP? This setting is _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
validateResponseSignature::
Should the client expect signed logout response documents from the IDP? _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
Should the client expect signed logout response documents from the IDP? This setting is _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
requestBinding::
This is the SAML binding type used for communicating SAML requests to the IDP _OPTIONAL._.
The default value is POST, but you can set it to REDIRECT as well.
This is the SAML binding type used for communicating SAML requests to the IDP. This setting is _OPTIONAL._.
The default value is `POST`, but you can set it to REDIRECT as well.
responseBinding::
This is the SAML binding type used for communicating SAML responses to the IDP The values of this can be POST or REDIRECT _OPTIONAL._.
The default value is POST, but you can set it to REDIRECT as well.
This is the SAML binding type used for communicating SAML responses to the IDP The values of this can be `POST` or `REDIRECT`. This setting is _OPTIONAL._.
The default value is `POST`, but you can set it to `REDIRECT` as well.
postBindingUrl::
This is the URL for the IDP's logout service when using the POST binding. _REQUIRED_ if using the POST binding at all.
This is the URL for the IDP's logout service when using the POST binding. This setting is _REQUIRED_ if using the `POST` binding.
redirectBindingUrl::
This is the URL for the IDP's logout service when using the REDIRECT binding. _REQUIRED_ if using the REDIRECT binding at all.
This is the URL for the IDP's logout service when using the REDIRECT binding. This setting is _REQUIRED_ if using the REDIRECT binding.

20
topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc
View file

@ -1,7 +1,9 @@
===== IDP SingleSignOnService sub element
The `SignleSignOnService` sub element defines the login SAML endpoint of the IDP.
The `SingleSignOnService` sub element defines the login SAML endpoint of the IDP.
The client adapter will send requests
to the IDP formatted via the settings within this element when it wants to login.
[source,xml]
----
@ -11,23 +13,27 @@ The `SignleSignOnService` sub element defines the login SAML endpoint of the IDP
requestBinding="post"
bindingUrl="url"/>
----
Here are the config attributes you can define on this element:
signRequest::
Should the client sign authn requests? _OPTIONAL._.
Should the client sign authn requests? This setting is _OPTIONAL._.
Defaults to whatever the IDP `signaturesRequired` element value is.
validateResponseSignature::
Should the client expect the IDP to sign the assertion response document sent back from an auhtn request? _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
Should the client expect the IDP to sign the assertion response document sent back from an auhtn request?
This setting _OPTIONAL._ Defaults to whatever the IDP `signaturesRequired` element value is.
requestBinding::
This is the SAML binding type used for communicating with the IDP _OPTIONAL._.
The default value is POST, but you can set it to REDIRECT as well.
This is the SAML binding type used for communicating with the IDP. This setting is _OPTIONAL._.
The default value is `POST`, but you can set it to `REDIRECT` as well.
responseBinding::
SAML allows the client to request what binding type it wants authn responses to use.
The values of this can be POST or REDIRECT _OPTIONAL._.
The values of this can be `POST` or `REDIRECT`. This setting is _OPTIONAL._.
The default is that the client will not request a specific binding type for responses.
bindingUrl::
This is the URL for the ID login service that the client will send requests to. _REQUIRED._.
This is the URL for the IDP login service that the client will send requests to. This setting is _REQUIRED._.

7
topics/saml/java/general-config/roleidentifiers_element.adoc
View file

@ -1,6 +1,9 @@
===== RoleIdentifiers element
The `RoleIdentifiers` element defines what SAML attributes within the assertion received from the user should be used
as role identifiers within the Java EE Security Context for the user.
[source,xml]
----
@ -11,10 +14,8 @@
</RoleIdentifiers>
----
This element is optional.
It defines which SAML attribute values in the assertion should be mapped to a Java EE role.
By default `Role` attribute values are converted to Java EE roles.
Some IDPs send roles via a `member` or `memberOf` attribute assertion.
You define one or more `Attribute` elements to specify which SAML attributes must be converted into roles.
You can define one or more `Attribute` elements to specify which SAML attributes must be converted into roles.

9
topics/saml/java/general-config/sp-keys.adoc
View file

@ -2,22 +2,19 @@
===== SP Keys and Key elements
If the IDP requires that the SP sign all of its requests and/or if the IDP will encrypt assertions, you must define the keys used to do this.
If the IDP requires that the client application (SP) sign all of its requests and/or if the IDP will encrypt assertions, you must define the keys used to do this.
For client signed documents you must define both the private and public key or certificate that will be used to sign documents.
For encryption, you only have to define the private key that will be used to decrypt.
There are two ways to describe your keys.
Either they are stored within a Java KeyStore or you can cut and paste the keys directly within `keycloak-saml.xml` in the PEM format.
They can be stored within a Java KeyStore or you can or you can cut and paste the keys directly within `keycloak-saml.xml` in the PEM format.
[source,xml]
----
<Keys>
<Key signing="true" >
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<PrivateKey alias="http://localhost:8080/sales-post-sig/" password="test123"/>
<Certificate alias="http://localhost:8080/sales-post-sig/"/>
</KeyStore>
...
</Key>
</Keys>
----

19
topics/saml/java/general-config/sp-keys/key_pems.adoc
View file

@ -1,6 +1,21 @@
====== Key PEMS
Within the `Key` element you alternatively declare your keys and certificates directly using the sub elements `PrivateKeyPem`, `PublicKeyPem`, and `CertificatePem`.
Within the `Key` element you declare your keys and certificates directly using the sub elements
`PrivateKeyPem`, `PublicKeyPem`, and `CertificatePem`.
The values contained in these elements must conform to the PEM key format.
You usually use this option if you are generating keys using `openssl`
You usually use this option if you are generating keys using `openssl` or similar command line tool.
[source,xml]
----
<Keys>
<Key signing="true>
<PrivateKeyPem>
2341251234AB31234==231BB998311222423522334
</PrivateKeyPem>
<CertificatePem>
211111341251234AB31234==231BB998311222423522334
</CertificatePem>
</Key>
</Keys>
----

28
topics/saml/java/general-config/sp-keys/keystore_element.adoc
View file

@ -2,6 +2,24 @@
====== KeyStore element
Within the `Key` element you can load your keys and certificates from a Java Keystore. This is declared within
a `KeyStore` element.
[source,xml]
----
<Keys>
<Key signing="true" >
<KeyStore resource="/WEB-INF/keystore.jks" password="store123">
<PrivateKey alias="myPrivate" password="test123"/>
<Certificate alias="myCertAlias"/>
</KeyStore>
</Key>
</Keys>
----
Here are the XML config attributes that are defined with the `KeyStore` element.
file::
File path to the key store. _OPTIONAL._ The file or resource attribute must be set.
@ -12,8 +30,8 @@ resource::
password::
The password of the KeyStore _REQUIRED._
You can and must also specify references to your private keys and certificates within the Java KeyStore.
The `PrivateKey` and `Certificate` elements do this.
The `alias` attribute defines the alias within the KeyStore for the key.
For `PrivateKey`, a password is required to access this key specify that value in the `password` attribute.
If you are defining keys that the SP will use to sign document, you must also specify references to your private keys
and certificates within the Java KeyStore.
The `PrivateKey` and `Certificate` elements in the above example define an `alias` that points to the key or cert
within the keystore. Keystores require an additional password to access private keys.
In the `PrivateKey` element you must define this password within a `password` attribute.

26
topics/saml/java/general-config/sp_element.adoc
View file

@ -16,34 +16,36 @@ Here is the explanation of the SP element attributes
----
entityID::
This is the identifier for this client.
The IDP needs this value to determine who the client is that is communicating with it. _REQUIRED._
The IDP needs this value to determine who the client is that is communicating with it. This setting _REQUIRED._
sslPolicy::
This is the SSL policy the adapter will enforce.
Valid values are: ALL, EXTERNAL, and NONE.
For ALL, all requests must come in via HTTPS.
For EXTERNAL, only non-private IP addresses must come over the wire via HTTPS.
For NONE, no requests are required to come over via HTTPS.
This is _OPTIONAL._ and defaults to EXTERNAL.
Valid values are: `ALL`, `EXTERNAL`, and `NONE`.
For `ALL`, all requests must come in via HTTPS.
For `EXTERNAL`, only non-private IP addresses must come over the wire via HTTPS.
For `NONE`, no requests are required to come over via HTTPS.
This is _OPTIONAL._ and defaults to `EXTERNAL`.
nameIDPolicyFormat::
SAML clients can request a specific NameID Subject format.
Fill in this value if you want a specific format.
It must be a standard SAML format identifier, i.e. `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` _OPTIONAL._.
It must be a standard SAML format identifier, i.e. `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
This setting is _OPTIONAL._.
By default, no special format is requested.
forceAuthentication::
SAML clients can request that a user is re-authenticated even if they are already logged in at the IDP.
Set this to `true` if you want this. _OPTIONAL._.
Set this to `true` if you want this. This setting is _OPTIONAL._.
Set to `false` by default.
isPassive::
SAML clients can request that a user is never asked to authenticate even if they are not logged in at the IDP.
Set this to `true` if you want this.
Do not use together with `forceAuthentication` as they are opposite. _OPTIONAL._.
Set to `false` by default.
Do not use together with `forceAuthentication` as they are opposite. This setting is _OPTIONAL._.
It is set to `false` by default.
turnOffChangeSessionIdOnLogin::
The session id is changed by default on a successful login on some platforms to plug a security attack vector (Tomcat 8, Jetty9, Undertow/Wildfly). Change this to true if you want to turn this off This is _OPTIONAL_.
The default value is _false_.
The session id is changed by default on a successful login on some platforms to plug a security attack vector (Tomcat 8, Jetty9, Undertow/Wildfly).
Change this to `true` if you want to turn this off. It is recommended you do not turn it off.
The default value is `false`.

29
topics/saml/java/general-config/sp_principalname_mapping_element.adoc
View file

@ -2,10 +2,27 @@
===== SP PrincipalNameMapping element
This element is optional.
When creating a Java Principal object that you obtain from methods like HttpServletRequest.getUserPrincipal(), you can define what name that is returned by the Principal.getName() method.
When creating a Java Principal object that you obtain from methods like `HttpServletRequest.getUserPrincipal()`, you can
define what name that is returned by the `Principal.getName()` method.
[source,xml]
----
<SP ...>
<PrincipalNameMapping policy="FROM_NAME_ID"/>
</SP>
<SP ...>
<PrincipalNameMapping policy="FROM_ATTRIBUTE" attribute="email" />
</SP>
----
The `policy` attribute defines the policy used to populate this value.
The values are `FROM_NAME_ID`.
This policy just grabs whatever the SAML subject value is.
The other is `FROM_ATTRIBUTE`.
This will pull the value of Principal.getName() from one of the attributes in the SAML assertion received from the server.
The default value is `FROM_NAME_ID`.
The possible values for this attribute are:
FROM_NAME_ID::
This policy just uses whatever the SAML subject value is. This is the default setting
FROM_ATTRIBUTE::
This will pull the value from one of the attributes declared in the SAML assertion received from the server.
You'll need to specify the name of the SAML assertion attribute to use within the `attribute` XML attribute.