1.

On the host server, sign in to Okta with your Okta admin account that has a
minimum role of Super Admin and click Admin to access the Admin Console.
2. Click Directory > Directory Integrations.
a. Click Add Directory and then select Add Active Directory.
b. Review the installation requirements and click Set Up Active Directory.
c. Click Download Agent.
3. On the host server, locate the downloaded file and double-click the file to
launch the installer.
a. Click Yes at the message Do you want to allow the following
program to make changes to this computer?.
b. Choose an installation destination. Click Next.
c. Select the AD domain you want to manage with this agent. Click Next.
d. Select a domain user for the Okta AD agent to run as and click Next:
 Select Create or use the Okta Service account
(recommended) and complete the prompt to set a password.
Okta recommends using a complex password for security.
 Select Use an alternate account that I specify if you want to
assign the Okta AD Agent to run as an existing domain user.
e. Optional — If appropriate for your environment, specify a proxy server
through which your AD agent will connect. Click Next.
Note: If you are installing an AD agent version 3.4.11 or later, in
environments where internet traffic is required to go through a proxy, the
sign-in flow for the AD agent installer uses the proxy settings specified
within the installer. If no proxy settings are specified, the machine
defaults are used.
f. To register the AD Agent with the Okta service, enter your Okta
subdomain name. This is the <mycompany> part of the
example: <mycompany>.okta.com. Click Next.
g. On the Okta Sign In page, enter your admin username and password,
and then click Sign in.
h. The Okta AD agent requires several permissions. Click Allow Access. The
agent installation completes.
Note: If the error message displays The underlying connection was
closed. Could not establish trust relationship for the SSL/TLS service
channel, see Troubleshooting.
i. Click Finish.
4. When the Active Directory agent has started, return to the browser and
click Next. On the following screens you will select some basic configuration
options. You can change these and other settings at a later time.
a. (First time installations for this domain only) At the Connect an
Organization Unit to Okta screen, select the OUs from which you want
to import users and groups.
b. Select the Okta Username format that you want AD-imported end
users to use when logging in to Okta and then click Next.
Choose from:
 Email address
 SAM Account Name
 User Principal Name (UPN)
Important: It is critical that the username format selected here be the
correct format when you first import users. Changing the value can cause
errors for existing users.
c. On the Import AD Users and Group dialog, click Next.
Note: To reconfigure OU and import settings, as well as other settings, return to
the Settings tab (Directory > Directory Integrations > Active Directory
> Settings). For details, see Configure import and account settings.
5. On the Build User Profile tab, select the attributes that you want to use to
build your Okta user profiles. You can modify these attributes at a later time if
you want to accept the defaults at this time. Click Next.
To learn more about how Okta uses profiles and attributes, see About Universal
Directory and user profiles and Work with Active Directory user profiles and
attributes
6. Click Done. Agent setup is complete. Your AD domain is now integrated with
Okta. You are taken to the Settings tab where you can configure your import and
provisioning settings as described in Configure import and account settings
As you configure Desktop SSO (on prem or agentless) in your environment, be aware of
how the Desktop SSO flow works when importing users and how Just in Time (JIT)
authentication will occur.
 If using on-prem DSSO IWA always sends Okta the Universal Principal Name
(UPN). This is the only data Okta uses to look up a user. Okta does not perform
authentication for users because Kerberos validation is already done on the IIS
side.
 If using Agentless Desktop SSO, your web browser sends the Kerberos ticket to
Okta, and relies on the AD agent to look up the UPN. The Kerberos validation is
now done in the cloud in Okta.

When a user tries to sign in using Desktop SSO:

 If the user is already imported and active in Okta: Okta uses the UPN to
look up the user. If Okta finds the user, the profile reloads from AD and the user
signs in.
 If the user is imported but not yet active in Okta: Okta uses the UPN to
look up the user. If Okta finds the user, the profile loads from AD, is activated
and the user signs in.
 If the user has not been imported into Okta and JIT is on: Okta can only
validate the user by the UPN. So the Okta user name format must be the UPN in
order for the user to be successfully imported with JIT turned on. If the user
 name format is something other than the UPN, for example the email address or
SamAccountName, the search will fail to locate the user.
 If the user has not been imported into Okta and JIT is off: User sign in
will fail.

To enable Agentless DSSO:

1. In the Okta Admin dashboard, navigate to Security > Delegated
Authentication.
2. Scroll to Agentless Desktop SSO.
3. Click Edit and select a Desktop SSO mode:
o Off
o Test — For testing in your Preview environment.
o On — For enabling SSO in Production.
4. For Allowed network zones, add the zones that are associated with the
machines from which you will be implementing Agentless SSO.
Note: If IdP Discovery is turned on, the network zone options will not be
available. When IdP Discovery and Agentless DSSO are both on, Agentless DSSO
network zones are controlled through the IdP Routing Rules. You will update the
default IdP routing rule in STEP 5: Update the default DSSO Identity Provider
routing rule .
5. In AD Instances, select the Active Directory instance on which you configured
the SPN.
6. Configure Agentless Desktop SSO for this Active Directory domain with the
following information and then Save.
o Desktop SSO — Select Enable or Disabled depending on whether you
are enabling for production or testing.
o Service account username — This is the AD sign-on name that you
created in STEP 1: Create a service account and configure an SPN above,
without any domain suffix or Netbios name prefix. It can be the
sAMAccountName or the username part of the UPN. These two may be
the same string unless the Org admin chose to use different values.
o Service account password — Password for the account that you
created in AD.
o Validate service account credential on Save — (Optional) Validates
the service account credentials as an optional step in saving the Kerberos
realm configuration. If it's checked, the service account will be
 authenticated by the AD agent. If the credentials cannot be validated, an
error message appears. If you don't want to validate or can't because the
AD agent isn't responsive, the box can be unchecked to skip the
validation.
Once a domain has been configured and enabled users will be able to sign in with
Agentless DSSO.
The next step is to create an Identity Provider routing rule.

What is SAML?

SAML (Security Assertion Markup Language) is an XML-based standard for exchanging

authentication and authorization data between an identity provider (IdP) such as Okta,
and a service provider (SP) such as Box, Salesforce, G Suite, Workday, etc.

SAML completely changes the method by which a user signs into a service. Once an SP (e.g.
Box) is configured to authenticate via SAML, users attempting to access its service will no
longer be prompted to enter a username or password specific to the SP they are logging onto
(e.g. a Box username and password). Instead, an exchange between the SP and the configured
IdP will occur that will verify the user's identity and permissions, and then grant or deny
that user’s access to the SP. In other words, instead of using provided user credentials (like a
password) to verify a user, a SAML-configured service verifies that user's identity with the
IdP. Of course, this assumes the user has already logged into the IdP with a username and
password (and ideally multi-factor authentication as well!).

The first method, known as an SP-initiated flow, occurs when the user attempts to
sign onto a SAML-enabled SP via its login page or mobile application (for example, the
Box application on an iPhone). Instead of prompting the user to enter a password, an
SP that has been configured to use SAML will redirect the user to Okta. Okta will then
handle the authentication either by prompting the user to log into Okta, or via Desktop
Single Sign On. If the user’s credentials are correct and the user has been granted
access to the application on the Okta side, they will be redirected back to the SP as a
verified user.
The second flow is known as an IdP-initiated flow. This occurs when the user logs
into Okta (or launches Okta Mobile) and launches the SP application by clicking its
chiclet from their Okta home page. If the user has an account on the SP side, they will
be authenticated as a user of the application and will generally be delivered to its
default landing page (their actual destination within the SP's site is customizable). If
they do NOT currently have an account on the SP side, in some cases SAML can
actually create the user's account immediately in a process known as Just In Time
Provisioning (JIT - please consult our Provisioning Guide for more details)

Both IdP and SP initiated authentication flows rely upon assertions that are passed between
the user’s browser and URLs that are specifically created to handle SAML traffic (known
as endpoints). These assertions are in XML format and contain information that verifies who
the identity provider is, who the user is, and whether the user should have access to the SP. At
a basic level, a successful SP-initiated SAML flow occurs as follows:
1. The user (e.g. john@MyBusiness.com) navigates to the SP’s login page and
begins to log in. Some SPs offer a link to "sign in using SSO" on the login page,
whereas others can be configured to utilize SAML for all sign-on requests based
upon the domain portion of the username (e.g. users@MyBusiness.com). SPs
that utilize custom login pages (e.g. https://MyCompany.Dropbox.com) can often
be configured to utilize SAML for ALL login attempts.
2. The SP generates a SAML request and redirects the user to the Okta Single
Sign-On URL endpoint with the request embedded. This endpoint is unique for
each application within each Okta tenant.
3. Once the user is redirected to Okta they’ll need to enter their Okta credentials,
unless they had already authenticated into Okta in a previous session within the
same browser. In either case, a successful authentication request will redirect
 the user back to the SP’s Assertion Consumer Service (ACS) URL with an
embedded SAML response from Okta. At a minimum, the response will:
a. Indicate that it is indeed from Okta and hasn’t been altered, and contain a
digital signature proving such. This signature will be verified by the SP
using a public key from Okta that was previously uploaded to the SP as a
certificate.
b. Indicate that the user has authenticated successfully into Okta
c. Indicate who the user is via the NameID, a standard attribute used in
SAML assertions.
4. After the assertion is successfully parsed by the SP’s ACS, the user will then be
sent to the SP’s default relay state, which is usually the same page they’d
wind up if they’d simply logged into the SP with a username and password. As
SPs such as G Suite and Office 365 host several different services, the default
relay state will help dictate which specific service to send them to (for example,
directly to Outlook Webmail instead of Office 365’s main landing page).

SAML Tracer, a free add-on available for Firefox, is an extremely useful tool in helping
understand and troubleshoot SAML assertions. It allows you to extrapolate SAML
assertions from your browsing session and examine them line-by-line.

Why isn't the custom SAML app I've configured in Okta working?

We often receive support cases where one of the URLs is simply incorrect. This is
common because there's unfortunately not much of a standard as far as SAML
terminology is concerned. For example, some vendors may refer to the Assertion
Consumer Service or Entity ID by a term unique to them. Because of this discrepancy in
terminology, it can sometimes be a challenge to simply discover what information the
vendor is asking for, or what to do with the information they're providing.

To remove differing terminology from the equation, just remember that at a basic level,
you will need the vendor/developer to provide the following information to enter into
the custom application you've created in Okta:

1. The application's specific URL that SAML assertions from Okta should be sent to
(typically referred to as the ACS). In Okta, this is entered in the
application's Single Sign On URL field. Remember that this will very
likely not be the same URL as the application's basic login page, which generally
cannot receive or process SAML assertions.
2. The Audience Restriction, which dictates the entity or audience the SAML
Assertion is intended for. This field is frequently referred to as the "Entity ID" or
"Audience URI" by vendors. It can technically be any string of data up to 1024
 characters long but is usually in the form of a URL that contains the Service
Provider's name within, and is often simply the same URL as the ACS.
3. The username format expected by the application (i.e. email address, first initial
last name, etc)

The service provider will occasionally require that the assertion contains additional
attributes such as first name, last name, department, etc to help identify the user. In
such cases, be sure to ask the vendor to provide you with the Attribute Name (i.e.
firstName, lastName) and Name Format (Unspecified, URI Reference, and Basic) for
each required attribute.

You will also need to provide the vendor/developer with the following information from
the Okta application (accessed via the View Setup Instructions button in
the application's Sign On tab):

1. The Identity Provider Single Sign-On URL. The SP may refer to this as the
"SSO URL" or "SAML Endpoint." It's the only actual URL Okta provides when
configuring a SAML application, so it's safe to say that any field on the Service
Provider side that is expecting a URL will need this entered into it.
2. The Identity Provider Issuer. This is often referred to as the Entity ID or
simply "Issuer." The assertion will contain this information, and the SP will use it
as verification.
3. The x.509 Certificate. Some service providers allow you to upload this as file,
whereas others require you paste it as text into a field.

Some other troubleshooting and testing tips:

 We highly recommend installing SAML Tracer, a free and simple Firefox plugin
that will capture and display SAML assertions. This can help determine whether
the URL's are correct, whether the assertion is passing the required attributes,
whether the username is as expected, etc.
 During initial setup, it's a fairly common mistake to enter the application's
standard login page (e.g. https://account.box.com/login) in the Okta "Single Sign
On URL" field, instead of entering the application's ACS
(e.g. https://sso.services.box.net/sp/ACS.saml2). Since the standard login page
cannot process SAML assertions, this will result in one of two issues:
1. the user is directed to a page with a standard login prompt when they
attempt to launch the application
2. the user experiences an endless loop of being redirected to Okta, and
then back to the application's normal login page (which can't handle SAML
assertions), then back to Okta, etc. This can occur when the application
 utilizes a custom or "vanity" domain
(ie https://MyCompany.my.salesforce.com) that is configured to redirect
authentication to the IdP.
o A simple way to help verify whether you are entering the correct value in
the Single Sign On URL field is to simply try to navigate to it from a
browser. If the URL is indeed the vendor's ACS, you should receive an
error of some sort because you are navigating to the page without
sending an assertion to it. If a login prompt appears instead, it is very
likely that you have an incorrect Single Sign On URL.
 If you receive an error message indicating that the username is invalid or not
found, you'll first need to verify what username convention is expected on the SP
side and then verify that Okta is indeed sending proper usernames in the
assertion. You can verify what username the Okta application is sending by
navigating to the application's "Assignments" tab and clicking the pencil icon next
to an affected user. This will display the username that is being sent in the
assertion, and will need to match the username on the SP side.

If you've installed SAML Tracer and use it to extract the SAML assertion, it will display
the username as follows:
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-
format:unspecified">user@MyCompany.com</saml2:NameID>

Deployment Best Practices

Begin by verifying the following information from the Service Provider you intend to
integrate with Okta:

 Whether standard login methods are disabled once SAML is activated, and if so,
if there is another way for users to log in traditionally (using a username and
password) if Okta authentication is disrupted.
o If possible, it's best to create at least one "service account" on the SP side
that can bypass SAML and access its admin console via their login page.
This will allow a "back door" entry in the event that the SAML flow is
interrupted for any reason. Some service providers (G Suite, for example)
bypass SAML automatically if the user is a member of a particular
administrator group.
 The endpoint information discussed above
 Whether they support IDP and/or SP initiated authentication flows
 Whether they support potentially useful features such as JIT Provisioning
and Single Log Out (SLO)
 What SAML attributes they expect to receive in the assertion
We also recommend familiarizing yourself with tools such as Fiddler and the
aforementioned SAML Trace utility to examine the SAML assertion. Okta Support will
occasionally require output from one of these tools to help determine what is causing a
SAML assertion to fail.
 SAML is mostly used as a web-based authentication mechanism inasmuch as it relies
on using the browser agent to broker the authentication flow. At a high-level, the
authentication flow of SAML looks like this:

We are now ready to introduce some common SAML terms. We will go into the
technical details of these later – but it is important to understand the high-level concept
during the planning stage.

 A Service Provider (SP) is the entity providing the service – typically in the form of an
application
 An Identity Provider (IDP) is the entity providing the identities, including the ability to
authenticate a user. The Identity Provider typically also contains the user profile –
additional information about the user such as first name, last name, job code, phone
number, address, etc. Depending on the application, some service providers may require a
very simple profile (username, email), while others may require a richer set of user data
(job code, department, address, location, manager, etc).
 A SAML Request, also known as an authentication request, is generated by the Service
Provider to “request” an authentication.
 A SAML Response is generated by the Identity Provider. It contains the actual assertion of
the authenticated user. In addition, a SAML Response may contain additional information,
such as user profile information and group/role information, depending on what the
Service Provider can support.
 A Service Provider Initiated (SP-initiated) login describes the SAML login flow when
initiated by the Service Provider. This is typically triggered when the end user tries to
access a resource or login directly on the Service Provider side, such as when the browser
tries to access a protected resource on the Service Provider side.
 An Identity Provider Initiated (IDP-initiated) login describes the SAML login flow
initiated by the Identity Provider. Instead of the SAML flow being triggered by a redirection
from the Service Provider, in this flow the Identity Provider initiates a SAML Response that
is redirected to the Service Provider to assert the user’s identity.

As discussed earlier, an IDP-initiated login flow starts from the IDP. Since it begins on
the IDP side, there is no additional context about what the user is trying to access on
the SP side other than the fact that the user is trying to get authenticated and access
the SP. Typically, once the user is authenticated, the browser will be taken to a generic
landing page in the SP.

In an SP-initiated flow, the user tries to access a protected resource directly on the SP
side without the IDP being aware of the attempt. Two issues arise. First is the need to
identify the right IDP if authentication of a federated identity is needed. With SP-initiated
login, the SP initially does not know anything about the identity. As a developer, you
need to figure out how the SP can determine which IDP should be receiving the SAML
request. In some cases, if your application URLs contain subdomain information that is
mapped to a unique tenant and IDP, then the resource link being hit is enough to
identify the IDP. If this isn’t the case, then you might need to prompt the end user for
additional information from the end user such as user id, email, or a company id;
something that allows the SP to identify which IDP the user attempting to access the
resource belongs to. Remember, you are only prompting for an identifier, not
credentials.

Another issue with SP-initiated login flow is the support for deep links. Most applications
support deep links. For example, you might receive a link to a document that resides on
a content management system. Ideally, if you need to authenticate prior to accessing
the document, you would like to be taken to the document immediately after
authentication.
SAML is an asynchronous protocol by design. The SP-initiated login begins the flow by
generating a SAML Authentication Request that gets redirected to the IDP. At this point,
the SP does not store any information about the request. When the SAML response
comes back from the IDP, the SP wouldn’t know anything about the initial deep-link that
triggered the authentication request. Luckily, SAML supports this with a parameter
called RelayState.

A RelayState is an HTTP parameter that can be included as part of the SAML request
and SAML response. In an SP-initiated login flow, the SP can set the RelayState
parameter in the SAML request with additional information about the request. A SAML
IDP, upon receiving the SAML request, will take the RelayState value and simply attach
it back as a HTTP parameter in the SAML response after the user has been
authenticated. This way, when the round trip completes, the SP can use the RelayState
information to get additional context about the initial SAML authentication request.

In the case of a deep link, the SP sets the RelayState of the SAML request with the
deep-link value. When the SAML response comes back, the SP can use the RelayState
value and take the authenticated user to the right resource.

Exposing SAML configuration in SP

As discussed before, the SP needs the IDP configuration in order to complete the SAML
setup. While many ISVs choose to do this via support and email, the better way to do
this is by exposing a self-service administrator page for your customer’s IT administrator
to enable SAML. SAML supports metadata on both the IDP and SP side. One way to
configure the IDP/SP relationship on the SP side is to build the ability to receive an IDP
metadata file and the ability to generate an SP metadata file for consumption by the
IDP. This is the preferred method.

However, some ISVs choose to allow configuration of several key SAML parameters
directly rather than through a metadata file. Typical parameters would include the IDP
redirect URL (for SAML Request), IssuerID, IDP Logout URL. The SP must also allow
the IDP public certificate to be uploaded or saved.

Using a metadata file is preferred because it can handle any future

additions/enhancements in your SAML support without making UI changes that would
otherwise be required if you expose specific SAML configuration parameters in your UI.

Enabling SAML for everyone vs a subset of users

Depending on the nature of your application, there might be reasons to allow only a
subset of users to be SAML enabled. Imagine an application that is accessed by
internal employees and external users like partners. The employees may SAML into the
app, while the external users may use a separate set of credentials. Even in cases
where the intent is to have all the users of a particular tenant be SAML-enabled, it might
be useful to enable just a subset of users during proof-of-concept, testing and roll-out to
test out authentication with a smaller subset of users before going-live for the entire
population.

Implementing a “backdoor”
This is particularly important where the entire population is intended to be SAML-
enabled in your application. Sometimes, there might be a mistake in the SAML
configuration – or something changes in SAML IDP endpoints. In any case, you do not
want to be completely locked out. Having a backdoor available for administrator(s) to
use to access a locked system becomes extremely important. This is often
accomplished by having a “secret” login URL that does not trigger a SAML redirection
when accessed. Typically, the administrator will use a username/password to login in
and make the necessary changes to fix the problem.

SAML for Mobile Native Apps

Because SAML is an HTTP-based protocol, supporting SAML in a native mobile app
may seem tricky. You can actually achieve this quite easily by including an embedded
webview in your native app to support the HTTP redirects. When launching the
webview, make sure you hit a URL on the SP side that will trigger a SAML redirect back
to the IDP. From that point on, the webview will carry out the SP-initiated login flow as it
would happen in a browser. When the SP finally receives the SAML response and
authenticates the user successfully, your native app can leave the webview and
proceed with the rest of the login bootstrap which typically involves generating some
sort of a token (for example, OAuth) which is stored by the native app for subsequent
access. This is a fairly common approach used by many ISVs to support SAML
integration with enterprises.

For more details, see the technical overview for Okta Mobile Connect.

Testing SAML
Use the Okta SAML validation tool to speed up the process of developing a SAML SP.

This tool makes it easy for you to send SAML Requests to your SAML SP. It allows you
to quickly change the contents of the SAML requests and simplifies the process of
debugging SAML issues by automatically decoding SAML payloads and displaying
server headers for you.

You can also install the SAML Tracer extension to Firefox for testing, or similar tools for
other browsers.
 SAML Toolkits
OpenSource toolkits that implement the SAML 2.0 specification for the WebSSO Profile
for Service Providers in different programming languages can help you build your
applications and integrations:

 .NET Framework 4.5 or above: Kentor Authentication Services

 .NET Framework 4 or below: ComponentSpace SAML 2.0 - Paid software, licenses start at $299
 Java: OpenSAML
 Java/Spring: Spring Security SAML
 PHP: SimpleSAMLphp
 Python: PySAML2
 Ruby: Ruby-SAML