Wyn Enterprise Administration Guide

Wyn Enterprise: Configure Single Sign-on (SSO)

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,

Configuring SSO with CAS Authentication Server

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,

  1. Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, Wyn.conf, and ensure the following,

    • AuthenticationProtocol option must be CAS.
    • Scheme is optional. If not specified in the configuration file, the value of the Scheme option will be set as CAS, by default.
    • Disabled option is used to disable the SSO function.
    • CasServerUrlBase option uses the base URL of the CAS server which is mandatory and must be provided by you.
      <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>
      
  2. 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>
    
  3. 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.

  4. 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.

Model Definition of SSO with CAS Authentication Server

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; }
}

Configuring SSO With Microsoft Azure AD

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,

  1. Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, Wyn.conf and ensure the following,

    • The AuthenticationProtocol option must be OIDC.
    • The Scheme option is optional. In case, you don't specify the Scheme option in the configuration file, the value of this option will be set to OpenIdConnect.
    • The Disabled option is used to disable the SSO function.
    • The Authority, ClientId, and ClientSecret options are mandatory and are available in your Azure AD application.
    • The CallbackPath option is optional and if not specified, the default value of this option is /signin-oidc. Ensure that the CallbackPath matches the Redirect URI specified in the Azure AD application.
    <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>
    
  2. 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>
    
  3. 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.

     <Cookie>
     <ShareCookie>false</ShareCookie>
     <SameSite>None</SameSite>
     <Secure>true</Secure>
     </Cookie>
    
  4. 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.

  5. 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.
    Microsoft Azure AD - SLO Authentication

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.

Configuring SSO With Google Cloud 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,

  1. Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, Wyn.conf, and ensure the following,

    • AuthenticationProtocol option must be OAUTH.
    • Scheme is optional. In case, you don't specify the Scheme option in the configuration file, the value of this option will be set to Oauth, by default.
    • Disabled option is used to disable the SSO function.
    • AuthorizationEndpoint, TokenEndpoint, UserInformationEndpoint, ClientId, and ClientSecret options are mandatory and are available in your Google Cloud Service.
    • CallbackPath is optional and if not specified, the default value of this option is /signin-oauth. Ensure that theCallbackPath matches the Redirect URI you specified in the 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>
    
  2. 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>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>
    
  3. 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.

     <Cookie>
     <ShareCookie>false</ShareCookie>
     <SameSite>None</SameSite>
     <Secure>true</Secure>
     </Cookie>
    
  4. 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.

  5. SLO (Single Logout) - SLO is not supported by Google Cloud Service.

Configuring SSO with Amazon Cognito 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,

  1. Install the Wyn Enterprise application version 6.0 or above.
  2. 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.
    SSO - Amazon Cognito User Pool

    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.
    SSO - Amazon Cognito App Client

Follow the below instructions to configure SSO with Amazon Cognito Service,

  1. Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, Wyn.conf, and ensure the following,

    • AuthenticationProtocol option must be OIDC.
    • Scheme is optional. In case, you don't specify the Scheme option in the configuration file, the value of this option will be set to OpenIdConnect, by default.
    • Authority, ClientId, and ClientSecret options are mandatory and are available in your user pool.
    • CallbackPath is optional and if not specified, the default value of this option is /signin-oidc. Ensure that theCallbackPath matches the Redirect URI you specified in the app client settings.
    <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>
    
  2. 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.

     <Cookie>
     <ShareCookie>false</ShareCookie>
     <SameSite>None</SameSite>
     <Secure>true</Secure>
     </Cookie>
    
  3. 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.

  4. SLO (Single Logout) - SLO is not supported by Amazon Cognito application.

  5. Note the following,

    • User Pool ID can be found in the General Settings of your user pool.
      SSO - Amazon Cognito User Pool Id
    • Region can be found in the URL of your User Pool Management page.
      SSO - Amazon Cognito Region

Configuring SSO with OKTA

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,

  1. Add SSO Configuration Node - Add the SSO configuration node to the Wyn configuration file, "Wyn.conf" and ensure the following,

    • AuthenticationProtocol option must be OIDC.
    • Scheme is optional. In case, you do not specify the Scheme option in the configuration file, the value of this option will be set to OpenIdConnect .
    • Authority option is the domain URL of your OKTA organization, you can obtain it from the address bar of the browser.
    • ClientId and ClientSecret options are mandatory and are available in your OKTA application settings.
    • CallbackPath is optional and if not specified, the default value of this option is set as /signin-oidc. Ensure that the CallbackPath matches the Redirect URI specified in your OKTA application.
    • For OKTA, the ResponseCode option must be code.
    <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>
    
  2. 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.

     <Server>
     <Cookie>
     <ShareCookie>false</ShareCookie>
     <SameSite>None</SameSite>
     <Secure>true</Secure>
     </Cookie>
     </Server>
    
  3. On finishing the above configurations, restart the Wyn service. Now, you can log in to the Wyn Enterprise application using your OKTA account.

  4. 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.
    OKTA - Logout Function