Add a Generic Header Application
Overview
The purpose of this tutorial is to walk through the process of setting up a header application through the Access Gateway AdminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. Console.
Prerequisites
- Access Gateway is installed and configured for use.
See Setup Access Gateway Using an OVA Image - Access Gateway has been configured to use your Okta tenant as iDPAn acronym for Identity Provider. It is a service that manages end user accounts analogous to user directories such as LDAP and Active Directory, and can send SAML responses to SPs to authenticate end users. Within this scenario, the IdP is Okta..
See Configure your Okta tenant as an Identity Provider for more information about configuring your Okta tenant as an idP. - You have administrator rights on your Okta tenant and can assign applications to users, and create groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups..
- An external header based application which requires protection.
- Appropriate DNS entries for both the legacy application and the exposed new URL exist.
Create the Application in Access Gateway
-
Navigate to your Access Gateway InstanceAn instance, or computer instance, is a virtual machine (VM) or individual physical computer, used to host a software appliance..
Note: Access Gateway creates a default self-signed certificate. For non-production deployments, this will be appropriate. Proceed past any security exceptions raised by your browser. For production deployments, a valid certificate can be installed and these exceptions will not be needed.
-
In the Access Gateway Admin Console, enter your login credentials and click Login.
Username: admin Password: <default password>
-
Click the Applications tab.
-
Click +Add to add a new application.
-
Select the Header Based option from the left column menu, and click Create.
The New Protected Application wizard will start and display the Essentials pane for the application being added.
-
In the Essentials pane specify the following:
Field Value Label A name for the application. Public DomainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). A fully qualified host name such as gw-header-appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in..<your domain> Group Enter the group containing the users who should have access to the application. Description [optional] An appropriate description for your application. -
Click Next.
-
The Attributesstep is used to add, edit, delete and test attributes. Click Next.
Adding attributes is covered in detail later in this tutorial. -
Leave all policies unchanged and click Done.
-
Click Next.
Note:The Attributes page provides a list of attributes that will be passed into the application. This page also provides the ability to add, edit, or remove any attribute.
Test the Application
The following steps assign the application to a test account and then execute the application to verify basic functionality.
Assign the application
-
Login to your Okta tenant as administrator.
-
Select Application > Applications.
-
Click the name of the newly added header application..
-
Select the Assignments tab.
-
Select .Assign > Assign To People.
-
Select an appropriate user and click Assign.
Note
esting is typically initially done using the same user who is associated with administering Access Gateway
-
Click Done..
Execute the Application
-
Return to the Access Gateway admin console.
-
On the row representing the newly added header app, select Goto application > IDP Initiated.
- Verify the results page displays all expected attribute values.
- Close the results page.
Define Okta Tenant Groups
Within your Okta Tenant you will need to define one or more groups representing the sections of your application being protected. See the policy guide for information on defining fine grained application policy. In addition you may define additional attribute field values required by your application but outside those provided by default.
To define groups within your Okta tenant:
-
Login to your Okta tenant as administrator.
-
Select Directory > Groups.
-
Using the Add Group button, create one or more groups.
-
Click the name of the newly added group and use the various menu items to add, and otherwise manage group membership.
Note
User and group management is outside the scopeA scope is an indication by the client that it wants to access some resource. of this document. See .Users and Groups for details of user and group management.
Associate Access Gateway App with Protected Resource
With a tested Access Gateway Application in place, the next step is that application with a protected resource.
In this section we will:
- Associate a protected application with an external URL.
- Associate one or more Okta tenant groups with an application.
- Define one or more policies to protect portions of an application.
-
Return to the Access Gateway admin console.
-
Select the Application tabl.
Note
You can move directly to an application by clicking its name in the Topology tab.
-
In the row containing the header application, click the pencil icon.
-
If required, expand the Essentials pane.
-
Replace the following values:
Field Value Example Public Domain External DNS entry https://gw-application.externally-visible.com Protected Resource Internal protected resource https://legacy.protected.com -
In the Groups field, add groups associated with this application.
-
Expand Advanced.
-
Set advanced fields as required.
-
Click Next.
Add Attributes.
To add an attribute click the plus icon. |
![]() |
To delete an attribute, select its row and click the delete icon |
![]() |
To modify an existing attribute, select its row and click the pencil icon. |
![]() |
For detailed information on the attribute options, see Application Attributes .
- Click the (+) icon
-
From the Data Source drop down select an appropriate data source.
-
From the Field drop down select a field name.
-
From the Type drop down select the appropriate target type, either Header or Cookie.
-
In the Name field enter the name for the header or cookie value expected by the legacy application.
For example, to map the idP field username to the header field login, we would create an attribute resembling: -
Click Okay when the attribute is complete. .
-
Repeat as required to add all fields required by the legacy application.
[Optional]Add policy

Important
By default the root, represented by '/', is protected by Access Gateway. However all users who can access the root can access any sub set of resources beneath the root. Policy can be used to protect subsets of the parent root URL
An overview of user policy can be found in Application Policy User Overview.
For details and examples of policy see Administration User Policy Guide.
To add a policy statement which protects an specific portion of an application,
- In the Policies tab click the (+) icon.
- Select one of:
Protected - Create a policy rule which protects a specific URI
Unprotected - Create a policy rule which marks a URL unprotected
Adaptive - - Create an adaptive policy rule
Protected Rule - Create a Protected policy rule. - Enter an appropriate Name for the rule.
- Enter the Resource Path to the URI being protected.
For example, a protected rule might protect the /secure URI. - Depending on the rule type, enter additional details such as Resource Matching Rule.
For example, to create a rule which allows only access to users with a valid username value to access the /secure/ uri,
we could create a Protected Rule with Resource Matching Rule regular expression username=* as shown. -
Repeat as required. Click Done when complete.
Test the Generic Header Application
-
Select IDP Initiated from the drop down menu to verify the application is working.
Note
Your Okta tenant administrator will need to assign the header application to you.
- Verify that the application is logged in as required.
Next Steps
- Add or review application settings. For more details see Application Settings.
- Add application behaviors. For details and examples of behaviors seeAdminister Behaviors
- Add fine grained policy to further protect resources.
An overview of user policy can be found in Application Policy User Overview.
For details and examples of policy see Administration User Policy Guide. - Extend existing policy using Custom configuration, see Advanced Policy.
- Define one or more certificates for use with this application. See Certificate Management
- Add supplemental database or LDAPLightweight Directory Access Protocol (LDAP) is a lightweight client-server protocol for accessing directory services, specifically X.500-based directory services. LDAP runs over TCP/IP or other connection oriented transfer services. based data stores. For more information see Administer DataStores