You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+49-27
Original file line number
Diff line number
Diff line change
@@ -90,7 +90,7 @@ The toolkit is hosted on github. You can download it from:
90
90
The toolkit is hosted at [Sonatype OSSRH (OSS Repository Hosting)](http://central.sonatype.org/pages/ossrh-guide.html) that is synced to the Central Repository.
91
91
92
92
Install it as a maven dependency:
93
-
```
93
+
```xml
94
94
<dependency>
95
95
<groupId>com.onelogin</groupId>
96
96
<artifactId>java-saml</artifactId>
@@ -441,7 +441,7 @@ If you want to use anything different than javax.servlet.http, you will need to
441
441
442
442
#### Initiate SSO
443
443
In order to send an AuthNRequest to the IdP:
444
-
```
444
+
```java
445
445
Auth auth =newAuth(request, response);
446
446
auth.login();
447
447
```
@@ -450,16 +450,18 @@ The AuthNRequest will be sent signed or unsigned based on the security settings
450
450
The IdP will then return the SAML Response to the user's client. The client is then forwarded to the Attribute Consumer Service of the SP with this information.
451
451
452
452
We can set a 'RelayState' parameter containing a return url to the login function:
453
-
```
453
+
```java
454
454
String returnUrl ='https://example.com';
455
455
auth.login(relayState=returnUrl)
456
456
```
457
-
The login method can receive 6 more optional parameters:
458
-
-*forceAuthn* When true the AuthNRequest will have the 'ForceAuthn' attribute set to 'true'
459
-
-*isPassive* When true the AuthNRequest will have the 'Ispassive' attribute set to 'true'
460
-
-*setNameIdPolicy* When true the AuthNRequest will set a nameIdPolicy element.
457
+
The login method can receive 3 more optional parameters:
458
+
-*authnRequestParams* which in turn allows to shape the AuthNRequest with the following properties:
459
+
-*forceAuthn* When true the AuthNRequest will have the `ForceAuthn` attribute set to `true`
460
+
-*isPassive* When true the AuthNRequest will have the `IsPassive` attribute set to `true`
461
+
-*setNameIdPolicy* When true the AuthNRequest will set a `NameIdPolicy` element
462
+
-*allowCreate* When true, and *setNameIdPolicy* is also true, the AuthNRequest will have the `AllowCreate` attribute set to `true` on the `NameIdPolicy` element
463
+
-*nameIdValueReq* Indicates to the IdP the subject that should be authenticated
461
464
-*stay* Set to true to stay (returns the url string), otherwise set to false to execute a redirection to that url (IdP SSO URL)
462
-
-*nameIdValueReq* Indicates to the IdP the subject that should be authenticated
463
465
-*parameters* Use it to send extra parameters in addition to the AuthNRequest
464
466
465
467
By default, the login method initiates a redirect to the SAML Identity Provider. You can use the *stay* parameter, to prevent that, and execute the redirection manually. We need to use that if a match on the future SAMLResponse ID and the AuthNRequest ID to be sent is required. That AuthNRequest ID must be extracted and stored for future validation, so we can't execute the redirection on the login. Instead, set *stay* to true, then get that ID by
@@ -474,7 +476,7 @@ Related to the SP there are 3 important endpoints: The metadata view, the ACS vi
474
476
475
477
##### SP Metadata
476
478
This code will provide the XML metadata file of our SP, based on the info that we provided in the settings files.
477
-
```
479
+
```java
478
480
Auth auth =newAuth();
479
481
Saml2Settings settings = auth.getSettings();
480
482
String metadata = settings.getSPMetadata();
@@ -494,7 +496,7 @@ Before the XML metadata is exposed, a check takes place to ensure that the info
494
496
495
497
##### Attribute Consumer Service(ACS)
496
498
This code handles the SAML response that the IdP forwards to the SP through the user's client.
497
-
```
499
+
```java
498
500
Auth auth =newAuth(request, response);
499
501
auth.processResponse();
500
502
if (!auth.isAuthenticated()) {
@@ -572,7 +574,7 @@ Before trying to get an attribute, check that the user is authenticated. If the
572
574
573
575
##### Single Logout Service (SLS)
574
576
This code handles the Logout Request and the Logout Responses.
575
-
```
577
+
```java
576
578
Auth auth =newAuth(request, response);
577
579
auth.processSLO();
578
580
List<String> errors = auth.getErrors();
@@ -592,7 +594,7 @@ If we don't want that processSLO to destroy the session, pass the keepLocalSessi
592
594
593
595
#### Initiate SLO
594
596
In order to send a Logout Request to the IdP:
595
-
```
597
+
```java
596
598
Auth auth =newAuth(request, response);
597
599
598
600
String nameId =null;
@@ -615,36 +617,56 @@ String sessionIndex = null;
615
617
if (session.getAttribute("sessionIndex") !=null) {
TheLogoutRequest will be sent signed or unsigned based on the security settings 'onelogin.saml2.security.logoutrequest_signed'
621
623
622
624
TheIdP will return the LogoutResponse through the user's client to the Single Logout Service of the SP.
623
625
624
626
We can set a 'RelayState' parameter containing a return url to the login function:
625
-
```
627
+
```java
626
628
String returnUrl = 'https://example.com';
627
629
auth.logout(relayState=returnUrl)
628
630
```
629
631
630
-
Also there are 7 optional parameters that can be set:
631
-
-nameId. That will be used to build the LogoutRequest. If not name_id parameter is set and the auth object processed a SAML Response with a NameId, then this NameId will be used.
632
-
-sessionIndex. Identifies the session of the user.
633
-
If a match on the LogoutResponse ID and the LogoutRequest ID to be sent is required, that LogoutRequest ID must to be extracted and stored for future validation, we can get that ID by
634
-
- stay. True if we want to stay (returns the url string) False to execute a redirection to that url (IdP SLS URL)
635
-
- nameidFormat. The NameID Format that will be set in the LogoutRequest
636
-
- nameIdNameQualifier. The NameID NameQualifier that will be set in the LogoutRequest
637
-
-nameIdSPNameQualifier. The NameID SP Name Qualifier that will be set in the LogoutRequest
638
-
- parameters. Use it to send extra parameters in addition to the LogoutRequest
639
-
640
-
By default the logout method initiates a redirect to the SAML Identity Provider. You can use the stay parameter, to prevent that, and execute the redirection manually. We need to use that
632
+
Also there are other 3 optional parameters that can be set:
633
+
-*logoutRequestParams* which in turn allows to shape the LogoutRequest with the following properties:
634
+
-*sessionIndex* Identifies the session of the user
635
+
-*nameId* That will be used to build the LogoutRequest. If no *nameId* parameter is set and the auth object processed a SAML Response with a `NameID`, then this `NameID` will be used
636
+
-*nameidFormat* The `NameID``Format` that will be set on the LogoutRequest
637
+
-*nameIdNameQualifier* The `NameID``NameQualifier` that will be set on the LogoutRequest
638
+
-*nameIdSPNameQualifier* The `NameID``SPNameQualifier` that will be set on the LogoutRequest
639
+
-*stay* True if we want to stay (returns the url string) False to execute a redirection to that url (IdP SLS URL)
640
+
-*parameters* Use it to send extra parameters in addition to the LogoutRequest
641
+
642
+
By default the logout method initiates a redirect to the SAML Identity Provider. You can use the *stay* parameter, to prevent that, and execute the redirection manually. We need to use that
641
643
if a match on the future LogoutResponse ID and the LogoutRequest ID to be sent is required, that LogoutRequest ID must be extracted and stored for future validation so we can't execute the redirection on the logout, instead set stay to true, then get that ID by
642
644
643
-
```
645
+
```java
644
646
auth.getLastRequestId()
645
647
```
646
648
and later executing the redirection manually.
647
649
650
+
### Extending the provided implementation
651
+
652
+
All the provided SAML message classes (`AuthnRequest`, `SamlResponse`, `LogoutRequest`, `LogoutResponse`) can be extended to add or change the processing behavior.
653
+
654
+
In particular, the classes used to produce outgoing messages (`AuthnRequest`, `LogoutRequest`, and `LogoutResponse`) also provide a `postProcessXml` method that can be overridden to customise the generation of the corresponding SAML message XML, along with the ability to pass in proper extensions of the input parameter classes (`AuthnRequestParams`, `LogoutRequestParams`, and `LogoutResponseParams` respectively).
655
+
656
+
Once you have prepared your extension classes, in order to make the `Auth` class use them, appropriate factories can then be
657
+
specified:
658
+
659
+
```java
660
+
// let AuthnRequestEx, SamlResponseEx, LogoutRequestEx, LogoutResponseEx be your extension classes
661
+
Auth auth =newAuth(request, response);
662
+
auth.setAuthnRequestFactory(AuthnRequestEx::new); // to make it build custom AuthnRequests
663
+
auth.setSamlResponseFactory(SamlResponseEx::new); // to make it build custom SamlResponses
664
+
auth.setOutgoingLogoutRequestFactory(LogoutRequestEx::new); // to make it build custom outgoing LogoutRequests
665
+
auth.setReceivedLogoutRequestFactory(LogoutRequestEx::new); // to make it build custom incoming LogoutRequests
666
+
auth.setOutgoingLogoutResponseFactory(LogoutResponseEx::new); // to make it build custom outgoing LogoutResponses
667
+
auth.setReceivedLogoutResponseFactory(LogoutResponseEx::new); // to make it build custom incoming LogoutResponses
668
+
// then proceed with login/processResponse/logout/processSLO...
0 commit comments