• Home
• Login with External IDP
• API Authentication Setup Guide

Single Sign On (SSO) For Your Apps Using API Authentication

---

API Authentication

miniOrange allows you to authenticate your users via API authentication provider into multiple applications.

This way, you can achieve Single Sign-On (SSO) into your applications where the users will need to authenticate themselves via your API Server only once and they can access all the configured applications.

What is API authentication?

Authentication is the method or process by which a user’s identity is verified and recognized. The credentials provided are usually verified against a user store like database, active directory, file etc. API is the interface that allows access to protected resources on request of a user. With remote access to resources it becomes necessary to ensure that only the authorized users have access to the resources. This is where API Authentication comes into play. API Authentication is the process of verifying the identity of the user trying to access resources on the server.

Authentication vs Authorization

Authentication is the process of verifying the identity of the user trying to access a resource and providing proof that the user is who they say they are.

Authorization is the mechanism by which one can determine the access level or user privileges of a resource. In simple terms authorization determines if the user in question has been allowed to access the requested resource. Usually authorization comes after authentication.

In short, authentication identifies who you are and authorization determines what you can do.

Types of API authentication methods

There are several implementations for API Authentication but the most popular authentication methods as follows:

• HTTP Basic Authentication
• HTTP Bearer Authentication
• API Key Authentication
• OAuth Authentication

In all API Authentication methods the aim is to generate a unique hash, token or api key that can be used to authorize further access to resources.

HTTP Basic Authentication

HTTP Basic Authentication is the most common and easiest of the authentication methods. Username and password of the user is combined and Base64 encoded. The result is then passed through a special HTTP header known as Authorization. When a user makes a request, the server decodes the Authorization header to verify the username and password. On successful authentication the user is provided access to the requested resource.

HTTP Bearer Authentication

HTTP Bearer Authentication is similar to HTTP Basic Authentication but uses security access token instead of username and password of the user. The access token is usually a random string generated by the server after successful authentication indicating that the user associated with this token has access to the requested resources. This token is sent in the HTTP Header Authorization by the user to access a certain resource. The HTTP Header is read by the server and validated to check if the it’s valid and should have access to the requested resource.

API Key Authentication

API Key Authentication is similar to HTTP Bearer Authentication but provides more flexibility of where the API Key/Token is sent in the request. API Key is usually a long string of alphanumeric characters usually generated at the time of first login or dynamically generated after successful authentication. On subsequent requests the API Key is sent in the request body or header. The server reads the API Key and validates if it’s a valid key and the authorized resources it can access. This method provides the flexibility to the admin to revoke access at any time.

OAuth Authentication

OAuth currently is the best choice for user authentication and authorization amongst all the authentication methods. In this method when users try to access a resource then they are prompted to authenticate themselves or login. After successful authentication a token is generated which can be used to access resources without having the user to authenticate themselves multiple times. OAuth also allows for better security with tighter scope checks and having a time validity for the tokens. As the token is revoked after a while there are less chances of being used by attackers to gain access to resources.

What are the different types of protocols?

SAML

SAML is a widely used XML based SSO standard for exchanging authentication and authorization data between an Identity Provider and Service Provider. It’s mostly used to authenticate and share user information across web applications in a secure manner.

OAuth/OAuth2

OAuth is a widely used authorization framework that allows two providers to share resources related to a user in a secure manner using scopes and time sensitive tokens.

OpenID

OpenId is the widely used authentication protocol. It's an authentication layer on top of OAuth2.0 used to verify the identity of the user. Compared to OAuth where user identity is not known OpenId provides a token with user information. This token can further be used to gain access to other resources if needed.

JWT

JWT or JSON Web Token is a standard on how data is created. It recommends a fixed JSON format for the token that is signed using a shared secret or private/public key. This is useful in OAuth and OpenID standards where tokens are exchanged containing user data.

We support REST API Authentication using API keys.

In API key authentication, a key-value pair is sent to the API Server either in Request headers or in request body.

Follow the Step-by-Step Guide given below for SSO for your apps using API Authentication

1. Fetch API endpoint information

• Note down the User Authentication URL and the API Key Value required for your API endpoint.

User Authentication URL	Your API Authentication provider URL. Eg: https://example.com/endpoint/
API Key	The API key value provided by your API Authentication Provider

2. Setup Custom API authentication source in miniOrange

• Login into your miniOrange Admin console and navigate to Identity Providers >> Add Identity Provider.



• Under the Choose Identity Provider, select API from the All dropdown.



• Search for Custom Login API and select it from the list.



• Provide an API identifier name.
• Under the Authentication Configuration section, paste the User Authentication URL that you copied in step 1 above.
• You can pass API key via two different methods i.e. Request Header or Request Body.

• Via Request Header
• Via Request Body

In this method, The API key is sent as "Authorization_key" via request header. You can refer to the example below.

• Provide the Header Name Authorization_key and its value i.e. Value of your API key that you copied in step 1.
• Select the Method as GET.
• Provide the Authentication Parameters as:



Authentication Parameters

{ "username":"##username##", "password":"##password##" }

Note: Extra parameters can be sent in the Authentication parameters section if required. These parameters are added in the format "parameter-name":"parameter-value".




• Provide the Status field’s value as status and Status Message field’s value as message.

Status	Name of field in the server response that contains the status code
Status Message	Name of the field that gives the description of the status in the response

• Authentication Response fields:
• Success Criteria: Enter the details as per the criteria you select.
• Error Status Message: Enter the error message field of the response.



• Click on the Save button.
• To check your configuration, click the three dots and select Test Authorization API.



• Enter your credentials when prompted and you should be able to see a Success message.

In this method, The API key is sent as "api_key" parameter in the POST body as JSON.

To configure your provider to send API key as a field in request body, you can refer below.

• In the headers section, provide the Header Name Content-Type and its value application/json.
  (The content-type in the header specifies what type of data is actually sent in the request. Some examples of Content-type can be: application/json; text/html; charset=UTF-8; multipart/form-data; text/plain, etc.)
• Select the Method as POST.
• Provide the Authentication Parameters as:



Authentication Parameters

{ "api_key":"value", "username":"##username##", "password":"##password##" }

Put the API key value that you copied in step 1 in place of 'value'.

Note: Extra parameters can be sent in the Authentication parameters section if required. These parameters can be added as fields in request body in the format "parameter-name":"parameter-value".




• Provide the Status field’s value as status and Status Message field’s value as message.

Status	Name of field in the server response that contains the status code
Status Message	Name of the field that gives the description of the status in the response

• Authentication Response fields:
• Success Criteria: Enter the details as per the criteria you select.
• Error Status Message: Enter the error message field of the response.



• Click on the Save button.
• To test the connection, select the user store you just added and click on Test Authorization API.



• Enter your credentials when prompted and you should be able to see a Success message.

3. Configure your app in miniOrange

• Login to miniOrange Admin Console.
• Go to Apps >> Add Application.

• SAML Application
• OAuth Application
• JWT Application

• Under Choose Application, select SAML/WS-FED from the All Apps dropdown.



• In the next step, search for your application from the list. If your application is not found, search for custom and you can set up your app via Custom SAML App. Click on Submit New App Request if you want to submit a new SSO application request.



• Under the Basic tab, you can configure the following settings.

  Display Name (required)	Enter the Display name for your app as per your preference.
  SP Entity ID or Issuer (required)	Is used to identify your app against the SAML request received from SP. The SP Entity ID or Issuer can be in either URL or in String format.
  ACS URL or Assertion Consumer Service URL (required)	Defines where the SAML Assertion should be sent after authentication. Make sure the ACS URL is in the format: https://www.domain-name.com/a/[domain_name]/acs
  Audience URL	As the name suggests, specifies the valid audience for SAML Assertion. It is usually the same as SP Entity ID. If Audience URL is not specified separately by SP, leave it blank.
  Single Logout URL	The URL where you want the logout request to be consumed and where your users should be redirected after single logout from the applications.
  Upload App Logo	Upload a logo for your application.




• Click Next to go to the Advanced settings. Configure the following settings.

  Signed Request	Enable this to sign the saml request sent by SP. Provide the X509 certificate or upload the certificate.
  Sign Response	Enable this if you want the entire SAML response to be signed.
  Sign Assertion	Enable this if you want only the assertion within the SAML response should be signed.
  Signature Algorithm	Select the algorithm that will be used to sign the SAML request/response.
  Encrypt Assertion	Select this if you want to encrypt the assertion in SAML response and provide the algorithm and certificate for encryption.
  Relay State	Enter the URL where you want the user to redirect after sign in to the application.
  Override Relay state	Enable this to override the default relay state of the SP.
  Logout Response Binding	A Logout Response is sent in reply to a Logout Request from SP. It could be sent by an Identity Provider or Service Provider.
  IdP initiated Logout Request Binding:	A Logout Response is sent in reply to a Logout Request from the IdP dashboard. It could be sent by an Identity Provider or Service Provider. HTTP Redirect - A Logout Response with its Signature HTTP POST - A Logout Response with the signature embedded
  SAML Authentication Validity Period	The time for which the authentication should be considered valid and the user should be able to perform SSO. After that, the user will have to sign in again.
  Enable Shared Identity	This feature lets you control whether a specific application can be accessed by shared user or not.




• Click Next to go to the Login Options tab. Here, you can configure the following settings:

  Primary Identity Provider	Select the identity source from where you want the authentication to happen. You will see the list of all configured sources.
  Force Authentication	Enable this to enforce authentication on each request to access the application.
  Show On End User Dashboard	Disable this if you do not want the app to be visible for all users on end user dashboard.




• Click Next to go to the Attributes tab. Here you can add and configure the attributes to be sent to the app.

  NameID	NameID is the unique identifier for the authenticated user included in the SAML assertion. It allows the Service Provider to recognize and map the user to an account. Generally, NameID is a username or Email Address.
  NameID Format	Defines what type of identifier is used in the NameID (e.g., email, persistent, transient) so the SP can correctly map the user. If the SP does not request a specific format, the IdP can leave it unspecified and use a default.
  Add Name Format	Name Format defines how attribute names are represented in a SAML assertion (e.g., as simple strings or URIs). It helps the SP correctly interpret attribute naming and ensures consistency between IdP and SP.
  Enable Multi-Valued Attributes	Enabled:Commas (,) and semicolons (;) are treated as separators, so the attribute is split into a clean list. Example: roles = ['admin', 'editor', 'viewer']. Disabled:Commas and semicolons are not treated as separators, so the attribute stays as one combined string. Example: roles = "admin;editor;viewer".
  Attribute Mapping	You can Add Attributes to be sent in SAML Assertion to SP. The attributes include user’s profile attributes such as first name, last name, full name, username, email, custom profile attributes, and user groups, etc.




• Click Next to go to the Policies tab. You need to Save the Application first to configure the policy for the application.



• After the application is saved you can configure the policy for that application.



• Click on the Assign group button. A new Configure Group Assignment modal tab will open.
  • Assign Group: Select the groups you want to link with the application. You can select up to 20 groups at a time.
  
  
  
  • If you need to create new group. Click on Add New Group button.
  • Enter the Group Name and click on Create Group.
  
  
  
  • Click on Next.
  • Assign Policies: Add the required policies to the selected groups. Enter the following details:
  • First Factor: Select the login method from the dropdown.
  • If you select Password as the login method, you can enable 2-Factor Authentication (MFA) and Adaptive Authentication, if needed.
  • If you select Password-less as login method, you can enable 2-Factor Authentication (MFA) if needed.



• Click on Save. Policies will be created for all the selected groups.
• You will see the policy listed once it’s successfully added.



• In the Metadata tab, click on any of the two tabs:
• Click on miniOrange as Idp If you want to use miniOrange as a User-Store i.e., your user identities will be stored in miniOrange.
• Click on External source as IdP If you want to authenticate your users via any external Identity Provider like Active Directory, Okta, OneLogin, etc. or any other custom IDPs.





• You can Download Metadata, Download Certficate, copy Metadata URL or copy Certificate based on your requirements.
• Similarly, you can get the values of SAML Login URL, SAML Logout URL, IDP Entity ID or issuer, IDP Logout URL, Metadata URL from here according to your metadata requirements.

• Under Choose Application, select OAuth/OpenID from the All Apps dropdown.



• Search for your application from the list. If your application is not found, search for oauth and you can set up your app via OAuth2/OpenID Connect.



• In the Basic tab, enter the following details:

  Display Name	Enter the Display Name (i.e., the name for this application).
  Redirect URL	Enter the Redirect URL. Make sure it follows this format: https://<mycompany.domain-name.com>
  Client ID	Auto-generated. Click the copy icon to use it in your application.
  Client Secret	Client Secret is hidden by default. Click the eye icon to reveal it and use the clipboard icon to copy it.
  Subject (Optional)	Select an attribute from the dropdown list.
  Description (Optional)	Add a description if required.
  Upload App Logo (Optional)	Upload an app logo (Optional). The app will be shown in the end-user dashboard with the logo that you configure here.

• Click on Save.



• You will be redirected to the Policies section.



• Click on the Assign group button. A new Configure Group Assignment modal tab will open.
  • Assign Group: Select the groups you want to link with the application. You can select up to 20 groups at a time.
  
  
  
  • If you need to create new group. Click on Add New Group button.
  • Enter the Group Name and click on Create Group.
  
  
  
  • Click on Next.
• Assign Policies: Add the required policies to the selected groups. Enter the following details:
• First Factor: Select the login method from the dropdown.
• If you select Password as the login method, you can enable 2-Factor Authentication (MFA) and Adaptive Authentication, if needed.
• If you select Password-less as login method, you can enable 2-Factor Authentication (MFA) if needed.



• Click on Save. Policies will be created for all the selected groups.
• You will see the policy listed once it's successfully added.



• You can go to the Advanced tab to change other settings, such as the expiry time for Access, JWT, and Refresh tokens.
• Access Token Expiry: For how long the provided access token should be valid from creation. [In Hours] A new access token has to be generated after the expiry.
• JWT Token Expiry: For how long the generated JWT token should be valid. [ In Hours ]
• Refresh Token Expiry: For how long the generated refresh token should be valid. [In Days] You will have to generate a new refresh token after the mentioned no. of days.
• Enable Shared Identity: This feature lets you control whether a specific application can be accessed by shared user or not.



• Switch to the Login options tab.

  Primary Identity Provider	Select the default ID source from the dropdown for the application. If not selected, users will see the default login screen and can choose their own IDP. [Choose miniOrange in this case.]
  SSO FLows	Select the desired SSO flow from the dropdown, such as miniOrange as IDP, miniOrange as Broker, or miniOrange as Broker with Discovery Flow.
  Show on Enduser Dashboard	Enable this option if you want to show this app in the end-user dashboard.
  Force Authentication	If you enable this option, users will have to log in every time, even if their session already exists.
  Allowed Logout URIs	Click the Allowed Logout URIs link to add a list of post-logout redirect URIs. Users will be redirected to one of these URIs after a successful logout from miniOrange.
  Single Logout Enabled	Enable this option to send logout requests to other applications when logging out from this app.
  Sign in URL	You can include user attributes in the sign-in URL using placeholders like {{username}}, {{primaryEmail}}, {{customAttribute1}}, etc. These placeholders will be dynamically replaced with the actual user values during the IdP-initiated SSO flow. You can generate url using following attributes: username, primaryEmail, alternateEmail, fname, lname, primaryPhone and customAttribute1. The url could be like this login.com/{{username}}/?primaryEmail={{primaryEmail}} Query Parameter Format: https://<sso-url>>?username={{username}} https://<sso-url>>?username={{username}}&email={{primaryEmail}} Path Parameter Format: https://<sso-url>>/{{customAttribute1}}/{{customAttribute2}}/?username={{username}}




• Switch to the Attributes tab.
• Enable Multi-Valued Attributes Option:



• When this option is enabled, both commas (,) and semicolons (;) are treated as delimiters. Any attribute containing these characters will be automatically split and converted into a multi-valued attribute based on their positioning.
• This feature ensures that attributes with multiple values are delivered in a structured format instead of as a single concatenated string.
• For example: when this option is enabled, Attributes will be will appear as a list like roles = ['admin', 'editor', 'viewer'] instead of a single string like roles = "admin;editor;viewer".
• When this option is disabled, attributes stored as a single concatenated string with commas (,) and semicolons (;) are treated in the way they are stored instead of a structured list.
• In this case, commas (,) and semicolons (;) are not treated as separators, so the values remain combined in one string.
• Getting Required App Details / Updating App Information:
• Go to the Apps section from the side menu. From the list of configured apps, locate the app you created. Click the three-dot icon next to the app and select the Edit option.



• You can edit any of the above-mentioned details in case you want to change them.



• OAuth Endpoints:
• Authorization Endpoint [ https://<your-company-name>.xecurify.com/moas/idp/openidsso ]
• This endpoint is used to authenticate the end user with their miniOrange credentials. This authenticates the users and returns a response back to the redirect_url based on the parameters passed in the request. [Mainly the authorization code]
• This endpoint takes the following parameters:
• Client_id: client_id of the application as configured in the previous steps
• Redirect_uri: The callback URL where you want to return the response
• scope: scope of authorization or level of access, you can send a single or multiple scopes separated by ‘+’. e.g “email+openid”. We support the following scopes :
• Email: returns the email address of the user in the response
• Profile: returns user profile information in the response
• OpenID: returns the id_token containing user profile details.
• This returns the authorization code and the state parameters in the response.
• Token Endpoint [ https://<your-company-name>.xecurify.com/moas/rest/oauth/token ]
• This endpoint returns the following:
• Id_token ​Contains user attributes and signatures which you have to validate with provided public certificate.

iss	https URI that indicates the issuer
sub	identifier of the user at the issuer
aud	client_id of the requesting client
nonce	the nonce parameter value received from the client
exp	expiration time of this token
iat	time when this token was issued
auth_time	time the authentication happened
at_hash	the first half of a hash of the access token

• Access_token: Valid for 1 hour and can be used to access user info or other endpoints until it is expired.
• This endpoint takes the following parameters in the request:
• Client_id: client_id of the application as configured in the previous steps.
• Client_secret: client_secret of the application as configured in the previous step.
• Redirect_url: The callback url where the response should be posted.
• Code: The authorization code received from the authorization endpoint.
• Grant_type: The OAuth grant you want to use for the request.
• User Info Endpoint [ https://<your-domain>.xecurify.com/moas/api/oauth/getuserinfo ] Required in case of OAuth Only
• This API can be used to fetch user profile information with an access token that was assigned to the user. A GET request is sent to the user info endpoint.
• You need to send the access token in the authorization header to receive the user details.
• OpenID Single Logout Endpoint [ https://<your-domain>.xecurify.com/moas/idp/oidc/logout?post_logout_redirect_uri ] :
• This endpoint removes the active user session from the miniOrange IDP and redirects the user to the URL mentioned in the post_logout_url parameter.

• Under Choose Application, select JWT from the All Apps dropdown.



• Search for your application from the list. If your application is not found, search for jwt and you can set up your app via JWT App.



• You can configure the following details in the application:

  Display Name	Enter the Display Name (i.e. the name for this application)
  Redirect URL	Enter the Redirect URL (i.e. the endpoint where you want to send/post your JWT token). You can add multiple redirect URLs by separating them with a ‘;’.E.g. abc.com;xyz.com
  Client ID	The Client ID is shown in the field below. Click the clipboard icon to copy it.
  Client Secret	Client Secret is hidden by default. Click the eye icon to reveal it and use the clipboard icon to copy it. This is used in the HS256 signature algorithm for generating the signature.
  Description (Optional)	Add a description if required.
  Upload App Logo (Optional)	Upload an app logo (Optional). The app will be shown in the end-user dashboard with the logo that you configure here.




• Click Save.
• You will be redirected to the Policies section.



• Click on the Assign group button. A new Configure Group Assignment modal tab will open.
  • Assign Group: Select the groups you want to link with the application. You can select up to 20 groups at a time.
  
  
  
  • If you need to create new group. Click on Add New Group button.
  • Enter the Group name and click on Create Group.
  
  
  
  • Click on Next.
  • Assign Policies: Add the required policies to the selected groups. Enter the following details:
  • First Factor: Select the login method from the dropdown.
  • If you select Password as the login method, you can enable 2-Factor Authentication (MFA) and Adaptive Authentication, if needed.
  • If you select Password-less as login method, you can enable 2-Factor Authentication (MFA) if needed.



• Click on Save. Policies will be created for all the selected groups.
• You will see the policy listed once it's successfully added.



• Click on Advanced tab.
• Enter the following details as required:

  Access Token	Enter the access token that will be sent to your redirect URL after a user logs in. This token helps your app know the user is allowed to access certain features.
  ID Token Expiry (In Mins)	Set how long (in minutes) the ID token will be valid. After this time, the user will need to log in again to get a new token.
  Subject	Choose what information, like the user’s email address, will be used to identify them in the token. This helps your app know which user is logged in.
  Signature Algorithm	Select your signature algorithm from the dropdown.
  The Logout URL of your application	Enter the web address where users should be sent after they log out.
  Enable Shared Identity	This feature lets you control whether a specific application can be accessed by shared user or not.




• Signature Algorithms for JWT

RSA-SHA256

• Asymmetric, uses a set of private and public keys to generate and validate the signature which is included in the JWT token.
• The private key is used to generate the signature on the IDP side.
• The public key is used to verify the signature on the SP side.
• We provide the public key for this.



HS256

• Symmetric, uses the same secret key to generate and validate the signature
• The secret key in this case is configurable from the app configuration page.
• Switch to Login options tab.

  Primary Identity Provider	Select the default ID source from the dropdown for the application. If not selected, users will see the default login screen and can choose their own IDP. [Choose miniOrange in this case.]
  Force Authentication	If you enable this option, users will have to log in every time, even if their session already exists.
  Enable User Mapping	Enable this option, if you want the app to show which user is signed in when it responds.
  Show On End User Dashboard	Enable this option if you want to show this app in the end-user dashboard.




• Switch to Attributes tab.
• Enable Multi-Valued Attributes Option:



• When this option is enabled, both commas (,) and semicolons (;) are treated as delimiters. Any attribute containing these characters will be automatically split and converted into a multi-valued attribute based on their positioning.
• This feature ensures that attributes with multiple values are delivered in a structured format instead of as a single concatenated string.
• For example: when this option is enabled, Attributes will be will appear as a list like roles = ['admin', 'editor', 'viewer'] instead of a single string like roles = "admin;editor;viewer".
• When this option is disabled, attributes stored as a single concatenated string with commas (,) and semicolons (;) are treated in the way they are stored instead of a structured list.
• In this case, commas (,) and semicolons (;) are not treated as separators, so the values remain combined in one string.
• Navigate to Endpoints and copy the following details:



• Single Sign-On URL:
  • This URL is used to initiate user authentication to obtain the JWT token.
  • Take redirect_uri as one of the query parameters.
  • After successful authentication on the IDP end, an active user session is created in the IDP and the user is redirected to the redirect_uri with the JWT token.
• Single Logout URL:
  • This URL is used to log out the user from the IDP by removing the active user session.
  • Take redirect_uri as one of the query parameters.
  • After removing the active user session, the IDP redirects the user to the redirect_uri.
• Reply back URL for IdP initiated logout:
  • This URL is used to initiate the logout in case the JWT user login was IDP Initiated [User logged in to the dashboard
    first and then initiated the login for the app from the dashboard.]
  • After logging out the user from the IDP, the user is redirected to the IDP dashboard login page.

External References

• What is Identity Brokering?
• Learn more about SSO