Introduction
Wicket is software that is delivered as a service (also called SaaS) to our customers. The software was built with an API-first approach, meaning that all of the data operations and business transactions that can be done through the Wicket Administration Interface, can be accessed by integrators using our REST API.
This guide is technical in nature and is written for integrators with enough context and knowledge to get a jump start in their SSO integration process.
Central Authentication Service (CAS) and SSO
Single Sign-On is a key component of the Wicket service offering. It is delivered by a reference implementation of the Central Authentication Service architectural pattern. Apareo’s CAS application offers enterprise-grade SSO capabilities through an open and well-documented protocol which includes support for pluggable authentication (LDAP, database, X.509, 2-factor) and multiple protocols (CAS, SAML, OAuth, OpenID).
The CAS system is fully integrated into our SaaS infrastructure and its presence is fully transparent to our clients and integrators. CAS can act as the identity provider to enable single sign-on into other applications using Wicket’s credentials. Alternatively, CAS can act as a proxy delegating the authentication process to another identity provider while still acting as the entry point for SSO requests.
Wicket SSO via OAuth 2
Applications looking to use Wicket as an SSO provider can leverage OAuth 2.0 as the protocol for communication to CAS. This allows users to log in to third-party applications using their Wicket credentials for authentication purposes.
In this scenario, Wicket acts as the Identity Provider, and the external application is the Service Provider. Wicket CAS uses the Authorization Code grant type of the protocol. This is the only grant type currently supported.
The Wicket support team must first configure each new Service Provider that will be communicating with Wicket CAS for SSO purposes. You should submit a support request in order to get this set up in your Wicket instance. For this purpose you must provide the following information:
- Tenant: The name of the tenant that is making the request
- Service Provider Domains: The domain names from where SSO requests will originate. You should make a distinction between development, staging and production domains. Production domains will be whitelisted with https only. For local development, you should provide any custom ports that you may be using, along with the domain or IP address. The domain is whitelisted as root URL, so any path under the domain will be allowed to initiate SSO requests.
Once the service has been configured Wicket will provide the following information in order to configure the OAuth 2.0 integration on the service provider:
- ClientID: A unique identifier for the service provider
- ClientSecret: A secret key that must be treated securely
Wicket OAuth 2.0 Endpoints
The following section summarizes the OAuth 2.0 endpoints for Wicket’s SSO. Additional details, specification, and options can be found in CAS OAuth documentation.
Authorize Endpoint
The URL to call to obtain an authorization code:
- https://<tenant-name>-login.staging.wicketcloud.com/oauth2.0/authorize
Example call with parameters to be substituted:
- https://<tenant-name>-login.staging.wicketcloud.com/oauth2.0/authorize?client_id=ClientID&redirect_uri=redirect_uri&response_type=code
Upon redirection to the Authorization Endpoint, the user is prompted to login using their Wicket credentials (if they don’t already have a session) in a page that is hosted by Wicket CAS. This page can be configured with a custom logo and using CSS upon request.
The authorization endpoint does not make use or require the scope parameter.
Access Token Endpoint
The URL to call to exchange authorization code for an access token:
- https://<tenant-name>-login.staging.wicketcloud.com/oauth2.0/accessToken
Example HTTP POST:
- https://<tenant-name>-login.staging.wicketcloud.com/oauth2.0/accessToken
Post Parameter |
Value |
grant_type |
authorization_code |
client_id |
The Client ID provided by Wicket |
client_secret |
The Client Secret provided by Wicket |
code |
The code obtained in the OAuth Callback |
redirect_uri |
Your Redirect URL |
Optional - You may supply the Client ID and Client Secret as base64 encoded Authorization HTTP Header of the format ClientID:Secret.
User Info Endpoint
The URL to call to get information about the user using the access token:
- https://<tenant-name>-login.staging.wicketcloud.com/oauth2.0/profile
Example call with parameters to be substituted:
- https://<tenant-name>-login.staging.wicketcloud.com/oauth2.0/profile?access_token=access_token
Wicket SSO via SAML2
Applications looking to use Wicket as an SSO identity provider can leverage SAML 2 as the protocol for communication to CAS. This allows users to log in to third-party applications using their Wicket credentials for authentication purposes. You may want to refer to the CAS SAML2 documentation.
The Wicket support team must configure each new SAML Service Provider that will be communicating with Wicket CAS for SSO purposes. You should submit a support request in order to get this set up in your Wicket instance. For this purpose you must provide the following information:
- Tenant: The name of the tenant that is making the request
- Service provider’s EntityID. Likely a URL to the service.
- Service Provider’s MetaData URL
The Service Provider can use the following Wicket details to configure SAML2.
- Identity Provider MetaData URL:
- https://<tenant-name>-login.staging.wicketcloud.com/idp/metadata
- Unsolicited SAML Login Request URL (Useful for Testing):
- https://<tenant-name>-login.staging.wicketcloud.com/idp/profile/SAML2/Unsolicited/SSO?providerId=<EntityID>
- Expected Name ID Format: email or ID
- Username Attribute: Can be the personUUID or email
SAML2 Endpoint URLs
- /idp/error
- /idp/profile/SAML2/Redirect/SSO
- /idp/profile/SAML2/POST/SSO
- /idp/profile/SAML2/POST-SimpleSign/SSO
- /idp/profile/SAML2/POST/SLO
- /idp/profile/SAML2/Redirect/SLO
- /idp/profile/SAML2/Unsolicited/SSO
- /idp/profile/SAML2/SOAP/ECP
- /idp/profile/SAML2/SOAP/AttributeQuery
SSO Profile Attributes
The following Wicket Person details are included in the SSO Profile Attributes by default.
Attribute Name |
Purpose |
personUuid |
The Unique PersonUuid in Wicket. |
|
The Person’s primary unique email address. Also serves as Username. |
firstName |
The Person’s first name |
lastName |
The Person’s last name |
name |
A combination of First Name and Last Name |
We can configure additional attributes upon request.
Using an Authenticated User in the Wicket API
The access token cannot be used to access the Wicket’s API directly, but is used to obtain the authenticated user’s Wicket PersonUuid from the User Info Endpoint.
The PersonUuid can then be used as a parameter within Wicket API calls.
Wicket’s API credentials are obtained separately.
Getting Support
If you get stuck or need a kick-off call to get you on your way with the integration. Please visit our support portal and submit a request. https://support.wicket.io
Comments
0 comments
Please sign in to leave a comment.