Authenticating your APIs
One of DreamFactory's most popular features is the wide-ranging authentication support. While API Key-based authentication will suffice for many DreamFactory-powered applications, developers often require a higher degree of security through user-specific authentication. In some cases Basic HTTP authentication will get the job done, however many enterprises require more sophisticated and flexible approaches largely because of the growing adoption of Single Sign On (SSO)-based solutions such as Active Directory and LDAP, and use of third-party identity providers and solutions such as AWS Cognito, Auth0, and Okta.
You'll be pleased to know DreamFactory supports all of these options through a comprehensive set of authentication connectors. These connectors include Active Directory, LDAP, OAuth through well-known identity providers such as Facebook, GitHub, and Twitter, OpenID Connect, and SAML 2.0. In this chapter we'll walk you through all of the different authentication integration options at your disposal!
Authentication Fundamentals
All DreamFactory APIs are private by default, requiring at minimum an API key for authentication purposes. The API key is associated with a role-based access control (RBAC) which determines what actions the client responsible for supplying the API key can undertake with regards to the API. For instance, it's possible to create a read-only RBAC which ensures the client can't access the API's insertion, modification, or deletion endpoints if they exist. If you're interested in protecting a database-backed API, you could limit access to a specific table, view, or stored procedure.
Further, DreamFactory supports both anonymous and user-based authentication. The former pertains to the provision of solely an API key, meaning DreamFactory won't possess any additional information regarding the user responsible for issuing API calls through the client. However in many cases you'll want to identify the connecting user by requiring authentication via an authentication provider such as Active Directory, LDAP, or Okta. In fact, DreamFactory supports these providers and more, including:
- Basic Authentication
- Active Directory
- LDAP
- OpenID Connect
- OAuth, including support for providers such as Facebook and GitHub
- SAML 2.0
The Authentication Process
Regardless of whether the desired authentication approach is anonymous or user-based, you'll always supply an API key. This API key is passed along with the request via the X-DreamFactory-Api-Key header. DreamFactory will confirm the key exists (all API keys are listed under the web UIs API Keys tab), and then review the associated RBAC to confirm the request method and URI are permissible according to the RBAC definition.
When user-based authentication is used, DreamFactory will additionally expect a JSON Web Token (JWT) be passed along via the X-DreamFactory-Session-Token header. This JWT is generated by DreamFactory following a successful authentication against the authentication service provider. The following diagram outlines the authentication flow when using a third-party authentication provider such as Active Directory:
Once successfully authenticated, DreamFactory will generate the JWT and return it to the client. This JWT should then be submitted along with each subsequent request. DreamFactory will check the token's validity and signature, examine the associated user's assigned RBAC (role-based access controls can be assigned on a per user-basis via the user's Roles tab), and if everything checks out the API call will be processed. The following diagram outlines this process:
Oauth
DreamFactory currently supports many Oauth providers (Facebook Oauth, Google Oauth, GitHub Oauth and more). The menu for selecting and configuring Oauth services can be found in Security > Authentication > Service Type. The basics for configuring all the Oauth providers in DreamFactory are roughly the same. In this image we can see the common fields shared across the Oauth setup page.
Below is a description of each field in the OAuth setup form:
| Field | Description |
|---|---|
| Namespace | A required field defined by the user; must end with _oauth (e.g., google_oauth). |
| Label | The display name for the service. |
| Description | A brief description of the service if desired. |
| Default Role | The role that will be applied by default to an authenticated user. Roles are configured in API Generation & Connections > Role based Access. |
| Client ID | A required field using a public string used by the service to identify your app. |
| Client Secret | A required field using a private string used by the service to authenticate the identity of the application. |
| Redirect URL | A required field that redirects the user to the specified URL on successful login. |
| Icon Class | The icon to be displayed for this service. |
| Role per App | This is a selector for giving users authenticating with the OAuth service access to specific services within the DreamFactory app. |
If a specific OAuth provider requires additional fields, those will be included in that provider's service menu. For example, Azure AD OAuth requires a Tenant ID and a Resource field.
Active Directory
Assuming you already have an Active Directory service configured, configuring AD's use in DreamFactory is straight forward. Navigate to Security > Authentication and select Active Directory as the service. You will need to provide a Namespace that will be included in the URL structure for the request. Additionally you will need to provide the AD Host and the Base DN. You can provide an AD Admin Username and Password to access additional configuration in DreamFactory's UI for the AD authentication service, but it is not a requirement. You will also want to choose a Default Role for users authenticating via AD. Make sure that the Active slider is enabled with a checkmark and save. Users should be able to authenticate with their AD credentials from the WEB UI login page.
Standard LDAP
Setting up Standard LDAP is pretty basic requiring only a couple of fields to function. You will need to provide a Namespace, Default Role for authenticated users, the LDAP host, and the Base DN. Ensure that the Active slider has a checkmark and save. LDAP authentication should be functioning at this point.
Auth0 SSO
Here is what the setup page for Auth0 looks when first selecting the service:
Below is a description of each field in the Auth0 SSO setup form, explaining what to enter and where to find the required information:
| Field | Description |
|---|---|
| Service Type | Select Auth0 SSO to configure authentication using Auth0 as a SAML 2.0 provider. |
| Namespace | A required, unique identifier for this authentication service. Used in API URLs. Example: auth0_sso. |
| Label | A display name for this Auth0 SSO connection. This will appear in the UI. |
| Description | (Optional) A brief description of this Auth0 SSO configuration for your reference. |
| Active | Toggle to enable or disable this authentication service. Must be enabled for users to log in with Auth0. |
Advanced Options
| Field | Description |
|---|---|
| Default Role | Select the default role to assign to users who log in via this Auth0 SSO connection. Roles control access permissions and are managed in the Roles section. |
| Service Provider Name ID Format | Specifies the format for the SAML NameID. Default is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. Usually, you can leave this as default unless your IdP requires a different format. |
| Service Provider X.509 Certificate | (Optional) The public x509 certificate for your service provider (DreamFactory). Used for SAML assertions. |
| Service Provider Private Key | (Optional) The private key for your service provider. Used for signing SAML requests. |
| Relay State | (Optional) The URL to redirect users to after successful authentication. If left blank, DreamFactory will return a JSON response with user info and JWT. To include the JWT in your redirect, use a URL like http://example.com?jwt=_token_ (DreamFactory will replace _token_ with the actual JWT). |
| Issuer | The unique identifier (Entity ID) of your Auth0 SAML application. This is provided by Auth0 and identifies your IdP. |
| Identity Provider Login URL | The SSO URL from your Auth0 SAML application. This is where authentication requests are sent. |
| Signing Certificate | The public x509 certificate from your Auth0 SAML application. Used to verify SAML responses. |
| Icon Class | (Optional) CSS class for an icon to visually represent this SSO provider in the UI. Example: fa fa-lock. |
Role per App
| Field | Description |
|---|---|
| App / Role | (Optional) Assign specific roles to users based on the app they are accessing. This allows for fine-grained access control per application. |
Tip: You will find the required values for Issuer, Login URL, and Signing Certificate in your Auth0 dashboard under the SAML2 Web App Addon settings for your application.
Heroku Add-on SSO
Here is what the setup page for Heroku Add-on SSO looks like when first selecting the service:
Below is a description of each field in the Heroku Add-on SSO setup form:
| Field | Description |
|---|---|
| Service Type | Select Heroku Add-on SSO to configure authentication using Heroku's SSO integration. |
| Namespace | A required, unique identifier for this authentication service. Used in API URLs. |
| Label | A display name for this Heroku Add-on SSO connection. This will appear in the UI. |
| Description | (Optional) A brief description of this Heroku Add-on SSO configuration for your reference. |
| Active | Toggle to enable or disable this authentication service. Must be enabled for users to log in with Heroku SSO. |
Advanced Options
| Field | Description |
|---|---|
| Secret | The salt value used to verify the token. This is required and should match the value configured in your Heroku Add-on SSO settings. |
| Secret Type | Defines how to use the secret value. Select the appropriate method from the dropdown, as required by your Heroku Add-on SSO integration. |
Okta SAML
Here is what the setup page for Okta SAML looks like when first selecting the service:
Below is a description of each field in the Okta SAML setup form:
| Field | Description |
|---|---|
| Service Type | Select Okta SAML to configure authentication using Okta as a SAML 2.0 provider. |
| Namespace | A required, unique identifier for this authentication service. Used in API URLs. |
| Label | A display name for this Okta SAML connection. This will appear in the UI. |
| Description | (Optional) A brief description of this Okta SAML configuration for your reference. |
| Active | Toggle to enable or disable this authentication service. Must be enabled for users to log in with Okta SAML. |
Advanced Options
| Field | Description |
|---|---|
| Default Role | Select the default role to assign to users who log in via this Okta SAML connection. Roles control access permissions and are managed in the Roles section. |
| Service Provider Name ID Format | Specifies the format for the SAML NameID. Default is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. Usually, you can leave this as default unless your IdP requires a different format. |
| Service Provider X.509 Certificate | (Optional) The public x509 certificate for your service provider (DreamFactory). Used for SAML assertions. |
| Service Provider Private Key | (Optional) The private key for your service provider. Used for signing SAML requests. |
| Relay State | (Optional) The URL to redirect users to after successful authentication. If left blank, DreamFactory will return a JSON response with user info and JWT. To include the JWT in your redirect, use a URL like http://example.com?jwt=_token_ (DreamFactory will replace _token_ with the actual JWT). |
| Identity Provider Issuer | The unique identifier (Entity ID) of your Okta SAML application. This is provided by Okta and identifies your IdP. |
| Identity Provider Single Sign-On URL | The SSO URL from your Okta SAML application. This is where authentication requests are sent. |
| Identity Provider X.509 Certificate | The public x509 certificate from your Okta SAML application. Used to verify SAML responses. |
| Icon Class | (Optional) CSS class for an icon to visually represent this SSO provider in the UI. Example: fa fa-lock. |
SAML 2.0
Here is what the setup page for SAML 2.0 looks like when first selecting the service:
Below is a description of each field in the SAML 2.0 setup form:
| Field | Description |
|---|---|
| Service Type | Select SAML 2.0 to configure authentication using a generic SAML 2.0 provider. |
| Namespace | A required, unique identifier for this authentication service. Used in API URLs. |
| Label | A display name for this SAML 2.0 connection. This will appear in the UI. |
| Description | (Optional) A brief description of this SAML 2.0 configuration for your reference. |
| Active | Toggle to enable or disable this authentication service. Must be enabled for users to log in with SAML 2.0. |
Advanced Options
| Field | Description |
|---|---|
| Default Role | Select the default role to assign to users who log in via this SAML 2.0 connection. Roles control access permissions and are managed in the Roles section. |
| SP NameIDFormat | Specifies the format for the SAML NameID. Default is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. Usually, you can leave this as default unless your IdP requires a different format. |
| SP x509cert | (Optional) The public x509 certificate for your service provider (DreamFactory). Used for SAML assertions. |
| SP Private Key | (Optional) The private key for your service provider. Used for signing SAML requests. |
| Relay State | (Optional) The URL to redirect users to after successful authentication. If left blank, DreamFactory will return a JSON response with user info and JWT. To include the JWT in your redirect, use a URL like http://example.com?jwt=_token_ (DreamFactory will replace _token_ with the actual JWT). |
| IdP EntityId | The unique identifier (Entity ID) of your SAML 2.0 Identity Provider. This is provided by your IdP and identifies your IdP. |
| IdP SSO service URL | The SSO URL from your SAML 2.0 Identity Provider. This is where authentication requests are sent. |
| IdP x509cert | The public x509 certificate from your SAML 2.0 Identity Provider. Used to verify SAML responses. |
| Icon Class | (Optional) CSS class for an icon to visually represent this SSO provider in the UI. Example: fa fa-lock. |
OpenID Connect
Here is what the setup page for OpenID Connect looks like when first selecting the service:
Below is a description of each field in the OpenID Connect setup form:
| Field | Description |
|---|---|
| Service Type | Select OpenID Connect to configure authentication using an OpenID Connect provider. |
| Namespace | A required, unique identifier for this authentication service. Used in API URLs. |
| Label | A display name for this OpenID Connect connection. This will appear in the UI. |
| Description | (Optional) A brief description of this OpenID Connect configuration for your reference. |
| Active | Toggle to enable or disable this authentication service. Must be enabled for users to log in with OpenID Connect. |
Advanced Options
| Field | Description |
|---|---|
| Client ID | The client ID provided by your OpenID Connect provider. Required for authentication. |
| Client Secret | The client secret provided by your OpenID Connect provider. Required for authentication. |
| Redirect URL | The URL to which the provider will redirect after authentication. Must match the redirect URI registered with your provider. |
| Discovery Endpoint | The OpenID Connect discovery document endpoint (usually ends with /.well-known/openid-configuration). Used to auto-configure endpoints. |
| Auth Endpoint | (Optional) The authorization endpoint. If not set, will be discovered automatically. |
| Token Endpoint | (Optional) The token endpoint. If not set, will be discovered automatically. |
| User Endpoint | (Optional) The user info endpoint. If not set, will be discovered automatically. |
| JWKS URI | (Optional) The JSON Web Key Set URI for validating ID tokens. If not set, will be discovered automatically. |
| Scopes | (Optional) Space-separated list of scopes to request. Default is openid profile email. |
| Validate ID Token | (Optional) Enable to validate the ID token signature and claims. |
| Icon Class | (Optional) CSS class for an icon to visually represent this provider in the UI. Example: fa fa-user-circle. |