Document Management
How To and Troubleshooting
Single Sign-on (SSO) is an authentication scheme that allows a user to log in to the Wyn Enterprise application with a single identity to several related, yet independent software systems. SSO allow users to log in to the Wyn application once and access the services without re-entering the authentication factors. Wyn Enterprise introduces integration with other identity services that support OAuth2 authentication for SSO. In this article, you will find the instructions to configure an identity service as a federation gateway for one or more external identity providers.
Wyn Enterprise application supports several authentication protocols for SSO including the following,
CAS is a SSO protocol that permits a user to access multiple applications by providing their credentials (username and password) only once. CAS allows web applications to authenticate users without gaining access to the user's security credentials such as their password.
To enhance data security, on logging out from the CAS Authentication server, users are automatically logged out from the Wyn Enterprise application.
Note: 1. You need to manually assign the Organizations, Roles, and Permissions to your users logging in to the Wyn Enterprise application using SSO. 2. You cannot generate token for the users logging in using SSO.
Before configuring, make sure that you have installed the Wyn Enterprise application version 6.0 or above and have access to the CAS Authentication Server. Follow the below instructions to configure SSO with CAS Authentication Server,
Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, Wyn.conf, and ensure the following,
<Server> <Authentication> <SSO> <AuthenticationProtocol>CAS</AuthenticationProtocol> <Scheme>Enter Scheme Name</Scheme> <Disabled>false</Disabled> <CasServerUrlBase>Enter Your CAS Base URL Here</CasServerUrlBase> </SSO> </Authentication> </Server>
Set Cookie options - Cookie options are needed to maintain the login state of the users. Set the Cookie: SameSite to None* and Cookie: Secure to True to enable the cookies across user domains.
<Cookie> <ShareCookie>false</ShareCookie> <SameSite>None</SameSite> <Secure>true</Secure> </Cookie>
Configure Incognizant User Login - To allow the users not existing in the Wyn Enterprise application to log in to the application, set SSO:AllowIncognizantUser option to True. And, to prevent log in of the user not existing in the Wyn Enterprise application, import the allowed users to Wyn application and ensure that the Provider value of the imported users is same as the value of the SSO:Scheme option.
Configure SLO (Single Logout) - To enable SLO from CAS Authentication Server when users log out from the Wyn Enterprise application, set the SSO:EnableSLO property to True. If you want your users to log out from the Wyn Enterprise application only when they log out from CAS Authentication Server, add the following configurations in CAS Server's Service Definition File (located in the CAS Authentication Server),
"logoutType": "BACK_CHANNEL", "logoutUrl": "{wyn_url}/account/cas-slo"
Note: If the logout URL is not set as the default value SSO:CasServerUrlBase/logout, you need to specify the SSO:CasServerLogoutUrl.
public class SSOConfig { /// <summary> /// Authentication protocol used for SSO, available values are "CAS", "OIDC" and "OAUTH". /// </summary> public string AuthenticationProtocol { get; set; } /// <summary> /// The User-specified Authentication Scheme . /// </summary> public string Scheme { get; set; } /// <summary> /// Indicate whether the SSO config is disabled or not. /// </summary> public bool Disabled { get; set; } = false; /// <summary> /// Indicate whether to logout from the authentication server when logging out from Wyn. /// </summary> public bool EnableSLO { get; set; } = true; /// <summary> /// Whether to allow the incognizant user to log in to Wyn. /// </summary> public bool AllowIncognizantUser { get; set; } = true; /// <summary> /// The base URL of the CAS server. For example: https://my.cas.server:8443/cas. /// </summary> public string CasServerUrlBase { get; set; } /// <summary> /// The logout URL of the CAS server. For example: https://my.cas.server:8443/cas/logout. /// </summary> public string CasServerLogoutUrl { get; set; } /// <summary> /// Version of the CAS protocol. The default value of the version is 3. /// </summary> public int CasProtocolVersion { get; set; } = 3; /// <summary> /// Authority address for OIDC protocol. For example: https://accounts.google.com. /// </summary> public string Authority { get; set; } /// <summary> /// Metadata address for OIDC protocol. /// </summary> public string MetadataAddress { get; set; } /// <summary> /// Client id. /// </summary> public string ClientId { get; set; } /// <summary> /// Client secret. /// </summary> public string ClientSecret { get; set; } /// <summary> /// Scopes. /// </summary> public List<string> Scopes { get; set; } /// <summary> /// Callback path. The default value is "/signin-{scheme}". /// </summary> public string CallbackPath { get; set; } /// <summary> /// Response type. The default value is "code id_token". /// </summary> public string ResponseType { get; set; } = OpenIdConnectResponseType.CodeIdToken; /// <summary> /// Response mode. The default value is "form_post". /// </summary> public string ResponseMode { get; set; } = OpenIdConnectResponseMode.FormPost; /// <summary> /// Whether the metadata address requires HTTPS protocol or not. /// </summary> public bool RequireHttpsMetadata { get; set; } = false; /// <summary> /// Whether the user claims from the user information endpoint are needed. The default value is true. /// </summary> public bool GetClaimsFromUserInfoEndpoint { get; set; } = true; /// <summary> /// Whether to save tokens in the cookie. The default value is true. /// </summary> public bool SaveTokens { get; set; } = true; /// <summary> /// Whether to use PKCE. /// </summary> public bool UsePkce { get; set; } = false; /// <summary> /// Authorization endpoint for OAuth. /// </summary> public string AuthorizationEndpoint { get; set; } /// <summary> /// Token endpoint for OAuth. /// </summary> public string TokenEndpoint { get; set; } /// <summary> /// User information endpoint for OAuth. /// </summary> public string UserInformationEndpoint { get; set; } /// <summary> /// Claim mappings for generating principal claims. /// Key is the claim type, and the value is the property name of the user. /// </summary> public Dictionary<string, string> ClaimMappings { get; set; } }
Microsoft Azure AD (Active Directory), is a cloud based identity and access management service that helps users access various SAAS applications and other external resources. Azure AD is an enterprise identity service that provides SSO authentication to the users of an organization without using their security credentials. See the Microsoft Azure AD product overview for more information.
Before configuring, make sure that you have installed the Wyn Enterprise application version 6.0 or above and have access to the Microsoft Azure AD application. Follow the below instructions to configure SSO with Microsoft Azure AD,
Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, Wyn.conf and ensure the following,
<Server> <Authentication> <SSO> <AuthenticationProtocol>OIDC</AuthenticationProtocol> <Scheme>Microsoft</Scheme> <Disabled>false</Disabled> <AllowIncognizantUser>true</AllowIncognizantUser> <Authority>https://sts.windows.net/{your_directory(tenant)_id}</Authority> <ClientId>{your_client_id}</ClientId> <ClientSecret>{your_client_secret}</ClientSecret> <Scopes> <sys:string>openid</sys:string> </Scopes> <ClaimMappings> <sys:Item> <Key>sub</Key> <Value>sub</Value> </sys:Item> <sys:Item> <Key>name</Key> <Value>nickname</Value> </sys:Item> <sys:Item> <Key>given_name</Key> <Value>given_name</Value> </sys:Item> <sys:Item> <Key>family_name</Key> <Value>family_name</Value> </sys:Item> <sys:Item> <Key>email</Key> <Value>email</Value> </sys:Item> </ClaimMappings> </SSO> </Authentication> </Server>
Add Authentication Configuration - Add the following authentication configuration under the Server section of the wyn.conf file,
<Server> <Urls>http://*:51980</Urls> <Authentication> <OAuth> <sys:Item> <Key>microsoft</Key> <Value> <DisplayName>Microsoft Azure AD</DisplayName> <ClientId>{your_client_id}</ClientId> <ClientSecret>{your_client_secret}</ClientSecret> <AuthorizationEndpoint> https://login.microsoftonline.com/common/oauth2/v2.0/authorize</AuthorizationEndpoint> <TokenEndpoint> https://login.microsoftonline.com/common/oauth2/v2.0/token</TokenEndpoint> <UserInformationEndpoint> https://graph.microsoft.com/v1.0/me</UserInformationEndpoint> <Scopes> <sys:string>User.Read</sys:string> </Scopes> <ClaimMappings> <Id>id</Id> <Name>displayName</Name> <Surname>surname</Surname> <GivenName>givenName</GivenName> <Email>userPrincipalName</Email> <MobilePhone>mobilePhone</MobilePhone> </ClaimMappings> </Value> </sys:Item> </OAuth> </Authentication> </Server>
Set Cookie Options - Cookie options are needed to maintain the login state of the users. To enable the cookies across user domains, set the Cookie: SameSite to None and Cookie: Secure to True.
Configure Incognizant User Login - To allow users that do not exist in the Wyn Enterprise application to log in to the application, set the SSO:AllowIncognizantUser option to True. And, to prevent log in of the user not existing in the Wyn Enterprise application, import the allowed users to Wyn application and ensure that the Provider value of the imported users is same as the value of the SSO:Scheme option.
Configure SLO (Single Logout) - SLO is an authentication feature that enables your users to logout from your authentication application and be automatically logged out from all connected applications. To support SLO with the Wyn Enterprise application when logging out from your Microsoft account, provide the logout URL in your application registration. Note that, the logout URL path must be /account/oidc-slo. The hostname, localhost, is only allowed for testing.
Note: If you log in with a Microsoft Work or School account, your organization administrator should authorize the identity service to sign in and read the profiles of the organization users. To do this, the organization admin should log into the identity service with Microsoft Work or School account, and the admin will be redirected to a permission consent page, check the Consent on behalf of your organization option and tap Accept. Then, all the organization users can log into the identity service.
Google Cloud Service provides Cloud Identity as your Identity Provider (IdP) that supports OpenID Connect (OIDC) for SSO based access to the Wyn Enterprise application users. You can configure SSO to the Wyn Enterprise application with the Google Cloud Service.
Before configuring, make sure that you have installed the Wyn Enterprise application version 6.0 or above and have access to the Google Cloud Platform with a user account in Cloud Identity or Google Workspace. Follow the below instructions to configure SSO with Google Cloud Service,
<Server> <Authentication> <SSO> <AuthenticationProtocol>OAUTH</AuthenticationProtocol> <Scheme>Google</Scheme> <AuthorizationEndpoint>https://accounts.google.com/o/oauth2/v2/auth</AuthorizationEndpoint> <TokenEndpoint>https://www.googleapis.com/oauth2/v4/token</TokenEndpoint> <UserInformationEndpoint>https://www.googleapis.com/oauth2/v2/userinfo</UserInformationEndpoint> <ClientId>{your_client_id}</ClientId> <ClientSecret>{your_client_secret}</ClientSecret> <Scopes> <sys:string>openid</sys:string> <sys:string>profile</sys:string> <sys:string>email</sys:string> </Scopes> <ClaimMappings> <sys:Item> <Key>sub</Key> <Value>id</Value> </sys:Item> <sys:Item> <Key>name</Key> <Value>name</Value> </sys:Item> <sys:Item> <Key>given_name</Key> <Value>given_name</Value> </sys:Item> <sys:Item> <Key>family_name</Key> <Value>family_name</Value> </sys:Item> <sys:Item> <Key>email</Key> <Value>email</Value> </sys:Item> <sys:Item> <Key>avatar</Key> <Value>picture</Value> </sys:Item> </ClaimMappings> </SSO> </Authentication> </Server>
<Server> <Urls>http://*:51980</Urls> <Authentication> <OAuth> <sys:Item> <Key>google</Key> <Value> <DisplayName>GOOGLE</DisplayName> <ClientId>{your_client_id}</ClientId> <ClientSecret>{your_client_secret}</ClientSecret> <AuthorizationEndpoint> https://accounts.google.com/o/oauth2/v2/auth</AuthorizationEndpoint> <TokenEndpoint> https://www.googleapis.com/oauth2/v4/token</TokenEndpoint> <UserInformationEndpoint> https://www.googleapis.com/oauth2/v2/userinfo</UserInformationEndpoint> <CallbackPath>/signin-google</CallbackPath> <Scopes> <sys:string>openid</sys:string> <sys:string>profile</sys:string> <sys:string>email</sys:string> </Scopes> <ClaimMappings> <Id>id</Id> <Name>name</Name> <Surname>family_name</Surname> <GivenName>given_name</GivenName> <Email>email</Email> <Avatar>picture</Avatar> </ClaimMappings> </Value> </sys:Item> </OAuth> </Authentication> </Server>
SLO (Single Logout) - SLO is not supported by Google Cloud Service.
Amazon Cognito provides user pool and identity to support SSO based access to the Wyn Enterprise application. User pool is a user directory using which users can sign in to the Wyn Enterprise application through Amazon Cognito. Identity pool is used to provide AWS (Amazon Web Services) credentials to the users. To support OAuth authentication, Amazon Cognito provides an OAuth 2 authentication server for token handling and management for the authenticated users. For more information, see the Using Amazon Cognito hosted UI help article.
Before configuring, ensure the following,
Create an application client in the user pool of Amazon Cognito. To create the application client, follow the below instructions, i) Create a User Pool - The Required Attributes should contain name and a valid email. For more information, see the Create a User Pool - Amazon Cognito help article.
ii) Add an app client - For Allowed OAuth Flows select the Authorization code grant option and, for the Allowed OAuth Scopes select the openid, profile, and email options. For more information, see the Add an app client and set up the hosted UI - Amazon Cognito help article.
Follow the below instructions to configure SSO with Amazon Cognito Service,
<Server> <Authentication> <SSO> <AuthenticationProtocol>OIDC</AuthenticationProtocol> <Scheme>AWS</Scheme> <Authority>https://cognito-idp.{region}.amazonaws.com/{user_pool_id}</Authority> <ClientId>{your_client_id}</ClientId> <ClientSecret>{your_client_secret}</ClientSecret> <CallbackPath>/signin-aws</CallbackPath> <ResponseType>code</ResponseType> <Scopes> <sys:string>openid</sys:string> <sys:string>profile</sys:string> <sys:string>email</sys:string> </Scopes> <ClaimMappings> <sys:Item> <Key>sub</Key> <Value>sub</Value> </sys:Item> <sys:Item> <Key>name</Key> <Value>name</Value> </sys:Item> <sys:Item> <Key>given_name</Key> <Value>given_name</Value> </sys:Item> <sys:Item> <Key>family_name</Key> <Value>family_name</Value> </sys:Item> <sys:Item> <Key>email</Key> <Value>email</Value> </sys:Item> </ClaimMappings> </SSO> </Authentication> </Server>
SLO (Single Logout) - SLO is not supported by Amazon Cognito application.
Note the following,
OKTA is an authorization server as well as a resource server that provides authentication and authorization solutions. OKTA supports SSO for Wyn users to access their accounts using the OKTA credentials. OKTA uses OAuth 2.0 and OIDC (OpenID Connect) to perform authentication. OAuth 2.0 is used to delegate authorization and, OIDC is used to retrieve and store authentication information. For more information on OAuth and OIDC, see the OpenID Connect & OAuth 2.0 API help article from OKTA.
Before configuring, make sure that you have installed the Wyn Enterprise application version 6.0 or above and have access to the OKTA account. Click here to sign up for an OKTA developer account.
Follow the below instructions to configure SSO with OKTA Application Integration Service,
Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, "Wyn.conf" and ensure the following,
<Server> <Authentication> <SSO> <AuthenticationProtocol>OIDC</AuthenticationProtocol> <Scheme>OKTA</Scheme> <AllowIncognizantUser>true</AllowIncognizantUser> <Authority>https://dev-03535523-admin.okta.com/</Authority> <ClientId>{your_client_id}</ClientId> <ClientSecret>{your_client_secret}</ClientSecret> <ResponseType>code</ResponseType> <Scopes> <sys:string>openid</sys:string> <sys:string>profile</sys:string> <sys:string>email</sys:string> </Scopes> </SSO> </Authentication> </Server>
<Server> <Cookie> <ShareCookie>false</ShareCookie> <SameSite>None</SameSite> <Secure>true</Secure> </Cookie> </Server>
On finishing the above configurations, restart the Wyn service. Now, you can log in to the Wyn Enterprise application using your OKTA account.
Since the OIDC support of OKTA is not same as other services, the logout function disrupts when SSO is configured with the OKTA application. This needs to be fixed in the Wyn Enterprise application to support the logout function.