TWebAuth
Description
TWebAuth is a control to allow integartion with several authentication services.
Setup
In your TMS WEB Core project simply drop a TWebAuth component on your form and fill in the necessary service keys provided to you by the given service. The property namings for each service resemble the key/id to look for.
By default if there is login button provided by the service, it will be added to your TWebAuth control at runtime. If you want your button to be rendered inside a different element, please use the ElementID property for that service. For example, in case of Facebook:
Currently the supported services are:
- Apple
- Auth0
- Microsoft
With each of these services you're be required to register an application. After your application is registered, you'll be provided a unique identifier. You'll need to use this unique ID to link your application to the TWebAuth control.
Apple
Please follow these steps to aquire an identifier for the login service:
- At developer.apple.com open "Certificates IDs & Profiles".
- Click on "Identifiers" in the side panel then click the plus symbol next to "Identifiers" to create a new App ID.
- Select "App IDs"
- Select "App" type
- Enter an application discription and an explicit stlye Bundle ID (for example
com.exampleif the recommended convention is followed). - Go back to "Identifiers" and create a new identifier. This time select "Services IDs".
- Register a service with a proper description and identifier (for example com.example.signin if the convention is followed). This identifier will be used in
TWebAuth. - Once the new Service ID is created, you can find it by using the dropdown in "Identifiers".
- Click on the newly created Service ID.
- After you hit continue and save click in the identifier again. You'll be greeted with a checkbox that says "Sign In with Apple". Click on "Configure".
-
In the popup window register your domain
- Primary App ID: The App ID created in the 1-5th step.
- Domains and subdomains: Domain where this service will be used
- Return URLs: Apple will return here after authentication is completed. This is also the location where apple will send the user data after authentication.
Apple only returns the user object the first time the user authorizes the app. Persist this information from your app; subsequent authorization requests won’t contain the user object.
Properties
The properties correspond to the settings provided by Apple: https://developer.apple.com/documentation/sign_in_with_apple/clientconfigi
| Property name | Description |
|---|---|
| ButtonSettings | Various settings for the button. |
| ClientID | Corresponds to ClientConfigI.clientId. |
| ElementID | ElementID to render the button to. If not set, the button is rendered in the TWebAuth component. |
| Enabled | If set to True, the service is enabled. |
| Mode | Corresponds to ClientConfigI.usePopup. |
| Nonce | Corresponds to ClientConfigI.nonce. |
| RedirectURI | Corresponds to ClientConfigI.redirectURI. |
| State | Corresponds to ClientConfigI.state. |
| Visible | If set to True, a button is rendered. |
Methods
| Method name | Description |
|---|---|
| Login | Initiate the login flow. |
Auth0
To aquire a domain and client ID, please follow the registration guide by Auth0: https://auth0.com/docs/quickstart/spa/vanillajs#configure-auth0
After registration, you can assign the domain to the TWebAuth.Services.Auth0.Domain property and the client ID to the TWebAuth.Services.Auth0.ClientID property.
Properties
| Property name | Description |
|---|---|
| ClientID | Corresponds to Auth0ClientOptions.client_id. |
| Domain | Corresponds to Auth0ClientOptions.domain. |
| Enabled | If set to True, the service is enabled. |
| LogoutSettings | Logout options corresponding to LogoutOptions. |
| Mode | If popup mode is used, the login flow is started with loginWithPopup. Otherwise loginWithRedirect is used. |
Methods
| Method name | Description |
|---|---|
| Login | Initiate the login flow. |
| Logout | Initiate the logout flow. |
| IsAuthenticated: TJSPromise | Promise returns with a Boolean value indicating the status of the authentication. See isAuthenticated for details. |
To create an application and to aquire an app ID, please follow the Create an App guide from Facebook: https://developers.facebook.com/docs/development/create-an-app
After the application is created, the "Facebook Login" product needs to be added to your application:
- Click the "Set Up" button in the "Facebook Login" card.
- Select the "Web" option.
- Fill in the "Site URL". For local development use the url of the TMS web server. By default this URL is: http://localhost:8000
You can see your App ID in the Dashboard of your application. The App ID should be assigned to the TWebAuth.Services.Facebook.AppID property.
Properties
| Property name | Description |
|---|---|
| AppID | Corresponds to the appId parameter during the FB.init call. |
| ButtonSettings | Various settings for the button. |
| ElementID | ElementID to render the button to. If not set, the button is rendered in the TWebAuth component. |
| Enabled | If set to True, the service is enabled. |
| Visible | If set to True, a button is rendered. |
Methods
| Method name | Description |
|---|---|
| Login | Initiate the login flow. |
| Logout | Initiate the logout flow. Keep in mind, that using Logout might log the user out from Facebook too. See details here. |
| IsAuthenticated | Promise returns with a Boolean value indicating the status of the authentication. Uses FB.getLoginStatus. |
The supported service is Sign In With Google (not the same as the legacy Google Sign-in).
To create an application and to aquire a client ID, please follow the setup guide provided by Google to aquire a Google API client ID: https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid#get_your_google_api_client_id
The client ID should be assigned to the TWebAuth.Services.Google.ClientID property.
Properties
| Property name | Description |
|---|---|
| AutoSelect | Corresponds to IdConfiguration.auto_select. |
| ButtonSettings | Various settings for the button. |
| ClientID | Corresponds to IdConfiguration.client_id. |
| ElementID | ElementID to render the button to. If not set, the button is rendered in the TWebAuth component. |
| Enabled | If set to True, the service is enabled. |
| OneTapContext | Corresponds to IdConfiguration.context. |
| UXMode | Corresponds to IdConfiguration.ux_mode. |
| Visible | If set to True, a button is rendered. |
Methods
| Method name | Description |
|---|---|
| OneTapPrompt | Invokes the One Tap prompt. See google.accounts.id.prompt for details. |
| DisableAutoSelect | Call this method when a user signs out of your website. See google.accounts.id.disableAutoSelect for details. |
| RevokeAccess(AUserID: string) | Method to revoke the OAuth grant. See google.accounts.id.revoke for details. |
Microsoft
To create an application and to aquire a client ID, please follow the setup guide provided by Microsoft: https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-spa-app-registration
Finish your configuration by following the "Redirect URI: MSAL.js 2.0 with auth code flow" steps.
The client ID should be assigned to the TWebAuth.Services.Microsoft.ClientID property. The TWebAuth.Services.Microsoft.Authority property should be set to 'https://login.microsoftonline.com/<tenant-id>', where <tenant-id> equals to the Directory (tenant) ID of your application.
Properties
| Property name | Description |
|---|---|
| Authority | Corresponds to BrowserAuthOptions.authority. |
| ClientID | Corresponds to BrowserAuthOptions.clientId. |
| Context | Context of the button. |
| ElementID | ElementID to render the button to. If not set, the button is rendered in the TWebAuth component. |
| Enabled | If set to True, the service is enabled. |
| LoginSettings | Various login settings. See RedirectRequest and PopupRequest for details. |
| LogoutSettings | Various logout settings. See EndSessionRequest and EndSessionPopupRequest for details. |
| Mode | Property to set the login/logout mode to popup or redirect. |
| RedirectURI | Corresponds to BrowserAuthOptions.redirectURI. |
| Theme | Theme of the button. |
| Visible | If set to True, a button is rendered. The official Microsoft button has fixed dimensions. If that is not desired, please use a custom button and call the Login method. |
Methods
| Method name | Description |
|---|---|
| Login | Initiate the login flow. |
| Logout | Initiate the logout flow. |
| IsAuthenticated: Boolean | Function returns with a Boolean value indicating the status of the authentication. |
Properties for TWebAuth
| Property name | Description |
|---|---|
| Services | Property to contain the settings for each service. |
Events for TWebAuth
| Event name | Description |
|---|---|
| OnAppleSignIn | Event triggered when Apple has authorized sign-in. |
| OnAppleSignInError | Event triggered when error happens during Apple sign-in. |
| OnAuth0LocalSignOut | Event triggered when Auth0 signed out locally via the LocalLogout call. |
| OnAuth0SignIn | Event triggered when Auth0 has authorized sign-in. |
| OnFacebookSignIn | Event triggered when Facebook has authorized sign-in. |
| OnFacebookSignOut | Event triggered when user signs out via Services.Facebook.Logout. |
| OnGoogleRevoke | Event triggered when access is revoked through Services.Google.Revoke. |
| OnGoogleRevokeError | Event triggered when error happens while Services.Google.Revoke is being executed. |
| OnGoogleSignIn | Event triggered when Google has authorized sign-in. |
| OnMicrosoftSignIn | Event triggered when Microsoft has authorized sign-in. Does not work if redirect is used. |
| OnMicrosoftSignOut | Event triggered when user signs out via Services.Microsoft.Logout. Does not work if redirect is used. |