libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

saml example docs

Browse source
This commit is contained in:
Bill Burke 2015-09-30 16:51:21 -04:00
parent 2a36185419
commit d3bd0a67a7
4 changed files with 46 additions and 808 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

126
examples/saml/README.md
View file

@ -1,123 +1,29 @@
# Keycloak SAML + Picketlink Client Quickstarts
# Keycloak SAML
## Introduction
These quickstarts show using Keycloak Server's SAML support with Picketlink's SAML client adapter. These quickstarts run on JBoss Enterprise Application Platform 6 or WildFly.
These examples show using Keycloak Server's SAML support with Keycloak's SAML client adapter. These examples run on JBoss Enterprise Application Platform 6 or WildFly.
We recommend using the Keycloak Appliance Distribution to test the quickstarts as it has already some things pre-set for you.
There is individual README.md file specific for each quickstart in the particular subdirectory with the quickstart. Here are just some general info about the requirements for your OS etc.
We recommend using the Keycloak Demo Distribution to test the examples as it has already some things pre-set for you.
There is individual README.md file specific for each example. Here are just some general info about the requirements for running the examples.
## System Requirements
## Start the Demo Distribution
To run these quickstarts with the provided build scripts, you need the following:
See the documentation for more details.
1. Java 1.6 or Java 1.7, depending if you're using JBoss EAP or WildFly to run the quickstarts. You can choose from the following:
* OpenJDK
* Oracle Java SE
* Oracle JRockit
## Import the test realm
2. Maven 3.0.0 or newer, to build and deploy the examples
* If you have not yet installed Maven, see the [Maven Getting Started Guide](http://maven.apache.org/guides/getting-started/index.html) for details.
* If you have installed Maven, you can check the version by typing the following in a command line:
Next thing you have to do is import the test realm for these examples. Clicking on the below link will bring you to the
create realm page in the Admin UI. The username/password is admin/admin to login in. Keycloak will ask you to
create a new admin password before you can go to the create realm page.
mvn --version
[http://localhost:8080/auth/admin/master/console/#/create/realm](http://localhost:8080/auth/admin/master/console/#/create/realm)
3. The JBoss Enterprise Application Platform 6 distribution ZIP or the WildFly distribution ZIP.
* For information on how to install and run those servers, refer to the their documentation.
Import the testsaml.json file that is in the saml/ example directory.
## Build and Deploy
## Run the Quickstarts
```
$ mvn clean install wildfly:deploy
```
The root folder of each individual quickstart contains a README file with specific details on how to build and run the example. In most cases you do the following:
* [Start the JBoss server](#start-the-jboss-server)
* [Build and deploy the quickstarts](#build-and-deploy-the-quickstarts)
## About the Keycloak SAML Quickstarts
The *Keycloak SAML Quickstarts* provide a lot of examples about how to use *Keycloak SAML Support* to enable SSO for your applications.
Before running them you need to understand how they are related with each other. Basically, Keycloak server is used as SAML Identity Provider and each individual WAR is used as SAML Service Provider.
Keycloak actually uses *Picketlink Federation* library as base implementation of SAML support.
### Using SAML Tracer Firefox Add-On to Debug the SAML SSO Flow
If you want to understand even better how IdPs and SPs communicate with each other, you may want to configure the [SAML Tracer Add-On](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) to your Mozilla Firefox.
This is a nice way to debug and view SAML Messages, so you can take a look on how the IdP and SP exchange messages when establishing a SSO session.
### Start the JBoss Server
Before you deploy a quickstart, in most cases you need a running JBoss Enterprise Application Platform 6 or WildFly server. A few of the Arquillian tests do not require a running server. This will be noted in the README for that quickstart.
The JBoss server can be started a few different ways.
* [Start the JBoss Server With the _web_ profile](#start-the-jboss-server-with-the-web-profile): This is the default configuration. It defines minimal subsystems and services.
* [Start the JBoss Server with the _full_ profile](#start-the-jboss-server-with-the-full-profile): This profile configures many of the commonly used subsystems and services.
* [Start the JBoss Server with a custom configuration](#start-the-jboss-server-with-custom-configuration-options): Custom configuration parameters can be specified on the command line when starting the server.
The README for each quickstart will specify which configuration is required to run the example.
#### Start the JBoss Server with the Web Profile
To start JBoss Enterprise Application Platform 6 or WildFly with the Web Profile:
1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the JBoss server with the web profile:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
#### Start the JBoss Server with the Full Profile
To start JBoss Enterprise Application Platform 6 or WildFly with the Full Profile:
1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the JBoss server with the full profile:
For Linux: JBOSS_HOME/bin/standalone.sh -c standalone-full.xml
For Windows: JBOSS_HOME\bin\standalone.bat -c standalone-full.xml
#### Start the JBoss Server with Custom Configuration Options
To start JBoss Enterprise Application Platform 6 or WildFly with custom configuration options:
1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the JBoss server. Replace the CUSTOM_OPTIONS with the custom optional parameters specified in the quickstart.
For Linux: JBOSS_HOME/bin/standalone.sh CUSTOM_OPTIONS
For Windows: JBOSS_HOME\bin\standalone.bat CUSTOM_OPTIONS
### Build and Deploy the Quickstarts
See the README file in each individual quickstart folder for specific details and information on how to run and access the example.
#### Build the Quickstart Archive
In some cases, you may want to build the application to test for compile errors or view the contents of the archive.
1. Open a command line and navigate to the root directory of the quickstart you want to build.
2. Use this command if you only want to build the archive, but not deploy it:
For EAP 6: mvn clean package
For WildFly: mvn -Pwildfly clean package
#### Build and Deploy the Quickstart Archive
1. Make sure you [start the JBoss server](#start-the-jboss-server) as described in the README.
2. Open a command line and navigate to the root directory of the quickstart you want to run.
3. Use this command to build and deploy the archive:
For EAP 6: mvn clean package jboss-as:deploy
For WildFly: mvn -Pwildfly clean package wildfly:deploy
#### Undeploy an Archive
The command to undeploy the quickstart is simply:
For EAP 6: mvn jboss-as:undeploy
For WildFly: mvn -Pwildfly wildfly:undeploy
Keycloak Documentation
------------
The documentation is available from the following [link](https://docs.jboss.org/keycloak/docs/1.1.0.Final/userguide/html/saml.html).

241
examples/saml/post-with-encryption/README.md
View file

@ -1,85 +1,12 @@
picketlink-federation-saml-sp-with-encryption: PicketLink Service Provider With a Basic Configuration using SAML HTTP POST Binding With Encryption Support
===============================
Author: Pedro Igor
Level: Intermediate
Technologies: PicketLink Federation, SAML v2.0
Summary: Basic example that demonstrates how to setup an application as a SAML v2.0 Service Provider using SAML HTTP POST Binding with Signature Support.
Source: <https://github.com/jboss-developer/jboss-picketlink-quickstarts/>
# Keycloak SAML Client Adapter using HTTP POST Binding With Encrypted Assertions
## Introduction
What is it?
-----------
Basic example that demonstrates how to setup an application as a SAML v2.0 Service Provider using SAML HTTP POST Binding with Signature Support.
This example demonstrates Keycloak SAML 2.0 support in conjunction with a servlet secured by Picketlink's SAML SP client.
## Import the test realm
Make sure you've set up the Keycloak Server
--------------------------------------
The Keycloak Appliance Distribution comes with a preconfigured Keycloak server (based on Wildfly). You can use it out of
the box to run these demos. So, if you're using this, you can head to Step 2.
Alternatively, you can install the Keycloak Server onto any EAP 6.x, or Wildfly 8.x server, but there is
a few steps you must follow.
Obtain latest keycloak-war-dist-all.zip. This distro is used to install Keycloak onto an existing JBoss installation.
This installs the server.
$ cd ${wildfly.jboss.home}/standalone
$ cp -r ${keycloak-war-dist-all}/deployments .
To be able to run the demos you also need to install the Keycloak client adapter. For Wildfly:
$ cd ${wildfly.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-wildfly-adapter-dist.zip
For JBoss EAP 6.x
$ cd ${eap.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-eap6-adapter-dist.zip
For JBoss AS 7.1.1:
$ cd ${as7.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-as7-adapter-dist.zip
Unzipping the adapter ZIP only installs the JAR files. You must also add the Keycloak Subsystem to the server's
configuration (standalone/configuration/standalone.xml).
<server xmlns="urn:jboss:domain:1.4">
<extensions>
<extension module="org.keycloak.keycloak-subsystem"/>
...
</extensions>
<profile>
<subsystem xmlns="urn:jboss:domain:keycloak:1.0"/>
...
</profile>
Boot Keycloak Server
---------------------------------------
Where you go to start up the Keycloak Server depends on which distro you installed.
From appliance:
```
$ cd keycloak/bin
$ ./standalone.sh
```
From existing Wildfly/EAP6/AS7 distro
```
$ cd ${wildfly.jboss.home}/bin
$ ./standalone.sh
```
Import the Test Realm
---------------------------------------
Next thing you have to do is import the test realm for the demo. Clicking on the below link will bring you to the
If you haven't already done so, you need to import the test realm for this examples. Clicking on the below link will bring you to the
create realm page in the Admin UI. The username/password is admin/admin to login in. Keycloak will ask you to
create a new admin password before you can go to the create realm page.
@ -87,161 +14,13 @@ create a new admin password before you can go to the create realm page.
Import the testsaml.json file that is in the saml/ example directory.
Install Picketlink Modules into App server
------------------------------------------
## Build and Deploy
If you are running this example with the Keycloak application distribution, you can skip this step.
```
$ mvn clean install wildfly:deploy
```
You may have to upgrade your picketlink modules in your JBoss EAP or Wildfly distribution. See Picketlink docs for more details.
Create the Security Domain for JBoss EAP
---------------
If you are running this example with the Keycloak application distribution, you can skip this step.
These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.
You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain-eap.cli` script provided in the root directory of this quickstart.
1. Before you begin, back up your server configuration file
* If it is running, stop the JBoss server.
* Backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
* After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
2. Start the JBoss server by typing the following:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
3. Review the `configure-security-domain-eap.cli` file in the root of this quickstart directory. This script adds the `sp` domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:
JBOSS_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain-eap.cli
You should see the following result when you run the script:
The batch executed successfully
{
"outcome" => "success",
}
Create the Security Domain for WildFly
---------------
If you are running this example with the Keycloak application distribution, you can skip this step.
These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.
You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain-wildfly.cli` script provided in the root directory of this quickstart.
1. Before you begin, back up your server configuration file
* If it is running, stop the JBoss server.
* Backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
* After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
2. Start the JBoss server by typing the following:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
3. Review the `configure-security-domain-wildfly.cli` file in the root of this quickstart directory. This script adds the `sp` domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:
JBOSS_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain-wildfly.cli
You should see the following result when you run the script:
The batch executed successfully
{
"outcome" => "success",
}
Review the Modified Server Configuration for EAP
-----------------------------------
If you are running this example with the Keycloak application distribution, you can skip this step.
If you want to review and understand newly added XML configuration, stop the JBoss server and open the `JBOSS_HOME/standalone/configuration/standalone.xml` file.
The following `sp` security-domain was added to the `security` subsystem.
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
The configuration above defines a security-domain which will be used by the SP to authenticate users based on a SAML Assertion previously issued by a Identity Provider.
Review the Modified Server Configuration for WildFly
-----------------------------------
If you are running this example with the Keycloak application distribution, you can skip this step.
If you are using Wildfly, the security-domain should have the following configuration:
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.wildfly.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
SAML SP-Initiated Single Sign-On
-----------------------------------
The SAML v2.0 specification defines a specific SSO mode called *SP-Initiated SSO*. In this mode, the SSO flow starts at the Service Provider side.
Please, take a look at the following documentation for more details:
1. [SAML v2.0 SP-Initiated SSO](https://docs.jboss.org/author/display/PLINK/SP-Initiated+SSO)
Start JBoss Enterprise Application Platform 6 or WildFly with the Web Profile
-------------------------
1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the server with the web profile:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
Build and Deploy the Quickstart
-------------------------
_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._
1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. Type this command to build and deploy the archive:
For EAP 6: mvn clean package jboss-as:deploy
For WildFly: mvn -Pwildfly clean package wildfly:deploy
4. This will deploy `target/picketlink-federation-saml-sp-with-encryption.war` to the running instance of the server.
Access the application
---------------------
## Access the application
The application will be running at the following URL: <http://localhost:8080/sales-post-enc>.
*Note: A Service Provider alone is not very useful without an Identity Provider to authenticate users and issue SAML Assertions. Once you get this application deployed, please take a look at [About the PicketLink Federation Quickstarts](../README.md#about-the-keycloak-saml-quickstarts).*
Undeploy the Archive
--------------------
1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. When you are finished testing, type this command to undeploy the archive:
For EAP 6: mvn jboss-as:undeploy
For WildFly: mvn -Pwildfly wildfly:undeploy
Debug the Application
------------------------------------
If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.
mvn dependency:sources
mvn dependency:resolve -Dclassifier=javadoc

243
examples/saml/post-with-signature/README.md
View file

@ -1,86 +1,12 @@
picketlink-federation-saml-sp-post-with-signature: PicketLink Service Provider With a Basic Configuration using SAML HTTP POST Binding With Signature Support
===============================
Author: Pedro Igor
Level: Intermediate
Technologies: PicketLink Federation, SAML v2.0
Summary: Basic example that demonstrates how to setup an application as a SAML v2.0 Service Provider using SAML HTTP POST Binding with Signature Support.
Source: <https://github.com/jboss-developer/jboss-picketlink-quickstarts/>
# Keycloak SAML Client Adapter using HTTP POST Binding With Signatures
## Introduction
What is it?
-----------
Basic example that demonstrates how to setup an application as a SAML v2.0 Service Provider using SAML HTTP POST Binding with Signature Support.
This example demonstrates Keycloak SAML 2.0 support in conjunction with a servlet secured by Picketlink's SAML SP client.
## Import the test realm
Make sure you've set up the Keycloak Server
--------------------------------------
The Keycloak Appliance Distribution comes with a preconfigured Keycloak server (based on Wildfly). You can use it out of
the box to run these demos. So, if you're using this, you can head to Step 2.
Alternatively, you can install the Keycloak Server onto any EAP 6.x, or Wildfly 8.x server, but there is
a few steps you must follow.
Obtain latest keycloak-war-dist-all.zip. This distro is used to install Keycloak onto an existing JBoss installation.
This installs the server.
$ cd ${wildfly.jboss.home}/standalone
$ cp -r ${keycloak-war-dist-all}/deployments .
To be able to run the demos you also need to install the Keycloak client adapter. For Wildfly:
$ cd ${wildfly.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-wildfly-adapter-dist.zip
For JBoss EAP 6.x
$ cd ${eap.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-eap6-adapter-dist.zip
For JBoss AS 7.1.1:
$ cd ${as7.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-as7-adapter-dist.zip
Unzipping the adapter ZIP only installs the JAR files. You must also add the Keycloak Subsystem to the server's
configuration (standalone/configuration/standalone.xml).
<server xmlns="urn:jboss:domain:1.4">
<extensions>
<extension module="org.keycloak.keycloak-subsystem"/>
...
</extensions>
<profile>
<subsystem xmlns="urn:jboss:domain:keycloak:1.0"/>
...
</profile>
Boot Keycloak Server
---------------------------------------
Where you go to start up the Keycloak Server depends on which distro you installed.
From appliance:
```
$ cd keycloak/bin
$ ./standalone.sh
```
From existing Wildfly/EAP6/AS7 distro
```
$ cd ${wildfly.jboss.home}/bin
$ ./standalone.sh
```
Import the Test Realm
---------------------------------------
Next thing you have to do is import the test realm for the demo. Clicking on the below link will bring you to the
If you haven't already done so, you need to import the test realm for this examples. Clicking on the below link will bring you to the
create realm page in the Admin UI. The username/password is admin/admin to login in. Keycloak will ask you to
create a new admin password before you can go to the create realm page.
@ -88,162 +14,13 @@ create a new admin password before you can go to the create realm page.
Import the testsaml.json file that is in the saml/ example directory.
Install Picketlink Modules into App server
------------------------------------------
## Build and Deploy
If you are running this example with the Keycloak application distribution, you can skip this step.
```
$ mvn clean install wildfly:deploy
```
You may have to upgrade your picketlink modules in your JBoss EAP or Wildfly distribution. See Picketlink docs for more details.
Create the Security Domain for JBoss EAP
---------------
If you are running this example with the Keycloak application distribution, you can skip this step.
These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.
You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain-eap.cli` script provided in the root directory of this quickstart.
1. Before you begin, back up your server configuration file
* If it is running, stop the JBoss server.
* Backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
* After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
2. Start the JBoss server by typing the following:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
3. Review the `configure-security-domain-eap.cli` file in the root of this quickstart directory. This script adds the `sp` domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:
JBOSS_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain-eap.cli
You should see the following result when you run the script:
The batch executed successfully
{
"outcome" => "success",
}
Create the Security Domain for WildFly
---------------
If you are running this example with the Keycloak application distribution, you can skip this step.
These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.
You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain-wildfly.cli` script provided in the root directory of this quickstart.
1. Before you begin, back up your server configuration file
* If it is running, stop the JBoss server.
* Backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
* After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
2. Start the JBoss server by typing the following:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
3. Review the `configure-security-domain-wildfly.cli` file in the root of this quickstart directory. This script adds the `sp` domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:
JBOSS_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain-wildfly.cli
You should see the following result when you run the script:
The batch executed successfully
{
"outcome" => "success",
}
Review the Modified Server Configuration for EAP
-----------------------------------
If you are running this example with the Keycloak application distribution, you can skip this step.
If you want to review and understand newly added XML configuration, stop the JBoss server and open the `JBOSS_HOME/standalone/configuration/standalone.xml` file.
The following `sp` security-domain was added to the `security` subsystem.
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
The configuration above defines a security-domain which will be used by the SP to authenticate users based on a SAML Assertion previously issued by a Identity Provider.
Review the Modified Server Configuration for WildFly
-----------------------------------
If you are running this example with the Keycloak application distribution, you can skip this step.
If you are using Wildfly, the security-domain should have the following configuration:
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.wildfly.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
SAML SP-Initiated Single Sign-On
-----------------------------------
The SAML v2.0 specification defines a specific SSO mode called *SP-Initiated SSO*. In this mode, the SSO flow starts at the Service Provider side.
Please, take a look at the following documentation for more details:
1. [SAML v2.0 SP-Initiated SSO](https://docs.jboss.org/author/display/PLINK/SP-Initiated+SSO)
Start JBoss Enterprise Application Platform 6 or WildFly with the Web Profile
-------------------------
1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the server with the web profile:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
Build and Deploy the Quickstart
-------------------------
_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._
1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. Type this command to build and deploy the archive:
For EAP 6: mvn clean package jboss-as:deploy
For WildFly: mvn -Pwildfly clean package wildfly:deploy
4. This will deploy `target/picketlink-federation-saml-sp-post-with-signature.war` to the running instance of the server.
Access the application
---------------------
## Access the application
The application will be running at the following URL: <http://localhost:8080/sales-post-sig>.
*Note: A Service Provider alone is not very useful without an Identity Provider to authenticate users and issue SAML Assertions. Once you get this application deployed, please take a look at [About the PicketLink Federation Quickstarts](../README.md#about-the-keycloak-saml-quickstarts).*
Undeploy the Archive
--------------------
1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. When you are finished testing, type this command to undeploy the archive:
For EAP 6: mvn jboss-as:undeploy
For WildFly: mvn -Pwildfly wildfly:undeploy
Debug the Application
------------------------------------
If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.
mvn dependency:sources
mvn dependency:resolve -Dclassifier=javadoc

244
examples/saml/redirect-with-signature/README.md
View file

@ -1,87 +1,12 @@
picketlink-federation-saml-sp-redirect-with-signature: PicketLink Service Provider With a Basic Configuration using SAML HTTP Redirect Binding With Signature Support
===============================
Author: Pedro Igor
Level: Intermediate
Technologies: PicketLink Federation, SAML v2.0
Summary: Basic example that demonstrates how to setup an application as a SAML v2.0 Service Provider using SAML HTTP Redirect Binding With Signature Support.
Source: <https://github.com/jboss-developer/jboss-picketlink-quickstarts/>
# Keycloak SAML Client Adapter using HTTP Redirect Binding With Signatures
## Introduction
What is it?
-----------
Basic example that demonstrates how to setup an application as a SAML v2.0 Service Provider using SAML HTTP Redirect Binding With Signature Support.
This example demonstrates Keycloak SAML 2.0 support in conjunction with a servlet secured by Picketlink's SAML SP client.
## Import the test realm
Make sure you've set up the Keycloak Server
--------------------------------------
The Keycloak Appliance Distribution comes with a preconfigured Keycloak server (based on Wildfly). You can use it out of
the box to run these demos. So, if you're using this, you can head to Step 2.
Alternatively, you can install the Keycloak Server onto any EAP 6.x, or Wildfly 8.x server, but there is
a few steps you must follow.
Obtain latest keycloak-war-dist-all.zip. This distro is used to install Keycloak onto an existing JBoss installation.
This installs the server.
$ cd ${wildfly.jboss.home}/standalone
$ cp -r ${keycloak-war-dist-all}/deployments .
To be able to run the demos you also need to install the Keycloak client adapter. For Wildfly:
$ cd ${wildfly.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-wildfly-adapter-dist.zip
For JBoss EAP 6.x
$ cd ${eap.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-eap6-adapter-dist.zip
For JBoss AS 7.1.1:
$ cd ${as7.home}
$ unzip ${keycloak-war-dist-all}/adapters/keycloak-as7-adapter-dist.zip
Unzipping the adapter ZIP only installs the JAR files. You must also add the Keycloak Subsystem to the server's
configuration (standalone/configuration/standalone.xml).
<server xmlns="urn:jboss:domain:1.4">
<extensions>
<extension module="org.keycloak.keycloak-subsystem"/>
...
</extensions>
<profile>
<subsystem xmlns="urn:jboss:domain:keycloak:1.0"/>
...
</profile>
Boot Keycloak Server
---------------------------------------
Where you go to start up the Keycloak Server depends on which distro you installed.
From appliance:
```
$ cd keycloak/bin
$ ./standalone.sh
```
From existing Wildfly/EAP6/AS7 distro
```
$ cd ${wildfly.jboss.home}/bin
$ ./standalone.sh
```
Import the Test Realm
---------------------------------------
Next thing you have to do is import the test realm for the demo. Clicking on the below link will bring you to the
If you haven't already done so, you need to import the test realm for this examples. Clicking on the below link will bring you to the
create realm page in the Admin UI. The username/password is admin/admin to login in. Keycloak will ask you to
create a new admin password before you can go to the create realm page.
@ -89,162 +14,13 @@ create a new admin password before you can go to the create realm page.
Import the testsaml.json file that is in the saml/ example directory.
Install Picketlink Modules into App server
------------------------------------------
## Build and Deploy
If you are running this example with the Keycloak application distribution, you can skip this step.
```
$ mvn clean install wildfly:deploy
```
You may have to upgrade your picketlink modules in your JBoss EAP or Wildfly distribution. See Picketlink docs for more details.
Create the Security Domain for JBoss EAP
---------------
If you are running this example with the Keycloak application distribution, you can skip this step.
These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.
You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain-eap.cli` script provided in the root directory of this quickstart.
1. Before you begin, back up your server configuration file
* If it is running, stop the JBoss server.
* Backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
* After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
2. Start the JBoss server by typing the following:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
3. Review the `configure-security-domain-eap.cli` file in the root of this quickstart directory. This script adds the `sp` domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:
JBOSS_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain-eap.cli
You should see the following result when you run the script:
The batch executed successfully
{
"outcome" => "success",
}
Create the Security Domain for WildFly
---------------
If you are running this example with the Keycloak application distribution, you can skip this step.
These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.
You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain-wildfly.cli` script provided in the root directory of this quickstart.
1. Before you begin, back up your server configuration file
* If it is running, stop the JBoss server.
* Backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
* After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.
2. Start the JBoss server by typing the following:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
3. Review the `configure-security-domain-wildfly.cli` file in the root of this quickstart directory. This script adds the `sp` domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.
4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:
JBOSS_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain-wildfly.cli
You should see the following result when you run the script:
The batch executed successfully
{
"outcome" => "success",
}
Review the Modified Server Configuration for EAP
-----------------------------------
If you are running this example with the Keycloak application distribution, you can skip this step.
If you want to review and understand newly added XML configuration, stop the JBoss server and open the `JBOSS_HOME/standalone/configuration/standalone.xml` file.
The following `sp` security-domain was added to the `security` subsystem.
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
The configuration above defines a security-domain which will be used by the SP to authenticate users based on a SAML Assertion previously issued by a Identity Provider.
Review the Modified Server Configuration for WildFly
-----------------------------------
If you are running this example with the Keycloak application distribution, you can skip this step.
If you are using Wildfly, the security-domain should have the following configuration:
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.wildfly.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
SAML SP-Initiated Single Sign-On
-----------------------------------
The SAML v2.0 specification defines a specific SSO mode called *SP-Initiated SSO*. In this mode, the SSO flow starts at the Service Provider side.
Please, take a look at the following documentation for more details:
1. [SAML v2.0 SP-Initiated SSO](https://docs.jboss.org/author/display/PLINK/SP-Initiated+SSO)
Start JBoss Enterprise Application Platform 6 or WildFly with the Web Profile
-------------------------
1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the server with the web profile:
For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
Build and Deploy the Quickstart
-------------------------
_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._
1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. Type this command to build and deploy the archive:
For EAP 6: mvn clean package jboss-as:deploy
For WildFly: mvn -Pwildfly clean package wildfly:deploy
4. This will deploy `target/picketlink-federation-saml-sp-redirect-with-signature.war` to the running instance of the server.
Access the application
---------------------
## Access the application
The application will be running at the following URL: <http://localhost:8080/employee-sig>.
*Note: A Service Provider alone is not very useful without an Identity Provider to authenticate users and issue SAML Assertions. Once you get this application deployed, please take a look at [About the PicketLink Federation Quickstarts](../README.md#about-the-keycloak-saml-quickstarts).*
Undeploy the Archive
--------------------
1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. When you are finished testing, type this command to undeploy the archive:
For EAP 6: mvn jboss-as:undeploy
For WildFly: mvn -Pwildfly wildfly:undeploy
Debug the Application
------------------------------------
If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.
mvn dependency:sources
mvn dependency:resolve -Dclassifier=javadoc