Skip to content

Commit b54bff0

Browse files
committed
Document the new API and extensibility features in README
1 parent 41d95ac commit b54bff0

File tree

1 file changed

+49
-27
lines changed

1 file changed

+49
-27
lines changed

README.md

+49-27
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ The toolkit is hosted on github. You can download it from:
9090
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.
9191

9292
Install it as a maven dependency:
93-
```
93+
```xml
9494
<dependency>
9595
<groupId>com.onelogin</groupId>
9696
<artifactId>java-saml</artifactId>
@@ -441,7 +441,7 @@ If you want to use anything different than javax.servlet.http, you will need to
441441

442442
#### Initiate SSO
443443
In order to send an AuthNRequest to the IdP:
444-
```
444+
```java
445445
Auth auth = new Auth(request, response);
446446
auth.login();
447447
```
@@ -450,16 +450,18 @@ The AuthNRequest will be sent signed or unsigned based on the security settings
450450
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.
451451

452452
We can set a 'RelayState' parameter containing a return url to the login function:
453-
```
453+
```java
454454
String returnUrl = 'https://example.com';
455455
auth.login(relayState=returnUrl)
456456
```
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
461464
- *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
463465
- *parameters* Use it to send extra parameters in addition to the AuthNRequest
464466

465467
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
474476

475477
##### SP Metadata
476478
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
478480
Auth auth = new Auth();
479481
Saml2Settings settings = auth.getSettings();
480482
String metadata = settings.getSPMetadata();
@@ -494,7 +496,7 @@ Before the XML metadata is exposed, a check takes place to ensure that the info
494496

495497
##### Attribute Consumer Service(ACS)
496498
This code handles the SAML response that the IdP forwards to the SP through the user's client.
497-
```
499+
```java
498500
Auth auth = new Auth(request, response);
499501
auth.processResponse();
500502
if (!auth.isAuthenticated()) {
@@ -572,7 +574,7 @@ Before trying to get an attribute, check that the user is authenticated. If the
572574

573575
##### Single Logout Service (SLS)
574576
This code handles the Logout Request and the Logout Responses.
575-
```
577+
```java
576578
Auth auth = new Auth(request, response);
577579
auth.processSLO();
578580
List<String> errors = auth.getErrors();
@@ -592,7 +594,7 @@ If we don't want that processSLO to destroy the session, pass the keepLocalSessi
592594

593595
#### Initiate SLO
594596
In order to send a Logout Request to the IdP:
595-
```
597+
```java
596598
Auth auth = new Auth(request, response);
597599

598600
String nameId = null;
@@ -615,36 +617,56 @@ String sessionIndex = null;
615617
if (session.getAttribute("sessionIndex") != null) {
616618
sessionIndex = session.getAttribute("sessionIndex").toString();
617619
}
618-
auth.logout(null, nameId, sessionIndex, nameIdFormat);
619-
```
620+
auth.logout(null, new LogoutRequestParams(sessionIndex, nameId, nameIdFormat));
621+
```java
620622
The Logout Request will be sent signed or unsigned based on the security settings 'onelogin.saml2.security.logoutrequest_signed'
621623

622624
The IdP will return the Logout Response through the user's client to the Single Logout Service of the SP.
623625
624626
We can set a 'RelayState' parameter containing a return url to the login function:
625-
```
627+
```java
626628
String returnUrl = 'https://example.com';
627629
auth.logout(relayState=returnUrl)
628630
```
629631

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
641643
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
642644

643-
```
645+
```java
644646
auth.getLastRequestId()
645647
```
646648
and later executing the redirection manually.
647649

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 = new Auth(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...
669+
```
648670

649671
### Working behind load balancer
650672

0 commit comments

Comments
 (0)