# Admin Portal ## Introduction The Admin Portal provides an out-of-the-box UI for IT contacts to verify domains, configure SSO and Directory Sync connections, and more. Designed to remove friction, custom walk-through documentation for each identity provider means that IT contacts can onboard their organizations without high-touch support from your team. Easy to integrate and fully maintained and hosted by WorkOS, the Admin Portal makes Domain Verification, SSO, and Directory Sync setup simple, fast, and secure.  ## Workflow Options There are two main workflows for initiating an Admin Portal session for IT contacts. You can either share a link to the Admin Portal from the WorkOS dashboard, or you can seamlessly integrate Admin Portal into your application through WorkOS SDKs or APIs.  If you want to provide IT contacts with a link to the Admin Portal, in an email for example, then you would need to create that link in the WorkOS dashboard. However, if you are adding a button to open the Admin Portal from within your application, then you would need to use the API. | Workflow | Use cases | Security | Return URL and Success URLs | | ------------------------------- | :--------------------------- | :------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | Share a link from the dashboard | Setup only | Can be revoked; Automatically revoked on setup completion; Expires after 30 days | Not applicable | | Generate a link via the API | Setup and post-configuration | Cannot be revoked; Expires after 5 minutes | Can be configured on the [Admin Portal](https://dashboard.workos.com/admin-portal) page in the dashboard or specified as a parameter for the API | *** ## Before getting started To get the most out of these guides, you'll need: - A [WorkOS account](https://dashboard.workos.com/) ## API object definitions [Connection](https://workos.com/docs/reference/sso/connection) : Represents the method by which users of an organization sign in to your application. [Organization](https://workos.com/docs/reference/organization) : Describes an organization whose users sign in with an SSO connection, or whose users are synced with a Directory Sync connection. [Portal link](https://workos.com/docs/reference/admin-portal/portal-link) : A temporary link to initiate an Admin Portal session. ## (A) Setup link from WorkOS dashboard The Admin Portal setup link gives your customer access to a guided configuration experience through our Admin Portal. It instructs them how to verify a domain, configure their identity or directory provider, and more. If successfully configured, no other action is required and you'll see verified domains and/or active connections appear under the organization. First decide whether your customer will be configuring Domain Verification, Single Sign-On, Directory Sync, Log Streams, or all of the above. Once you generate a link, the customer will have access for 30 days or until configured. You'll need a [WorkOS dashboard account](https://dashboard.workos.com/) to create an organization that will represent the enterprise you are onboarding. ### Create organization Sign in to your WorkOS dashboard account and create a new organization.  ### Generate a setup link Click the "Invite IT contact" button, select the features to include and then click "Next." Enter the email of the IT contact for the organization to automatically send them a setup link, or click "Copy setup link." Only one link can be active at a time. After creating the initial link, you can click the "Manage" button to revoke the existing link before creating a new one. ### Sharing a setup link If you chose to copy the setup link you can share it over email, Slack or direct message. We also recommend including details on what the link does and how long the link is active. ## (B) Integrate with your app In this guide, we'll walk you through the full end-to-end integration of the Admin Portal into your application. > [Sign in](https://dashboard.workos.com/) to your WorkOS dashboard account to see code examples pre-filled with your test API keys and resource IDs. ### Configure Admin Portal redirects To integrate Admin Portal, configure a logo redirect URL in the production environment. The logo in Admin Portal uses this value to send users to your app unless you specify a `return_url` when generating the Admin Portal link. You can also configure success URLs for Single Sign-On, Directory Sync, Log Streams, and Domain Verification setup flows. > Redirect URLs must use HTTPS. Configure these links on the [Admin Portal](https://dashboard.workos.com/admin-portal) page in the dashboard.  ### Install the WorkOS SDK WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application's language. Install the SDK using the command below. :::code-group{title="Install the WorkOS SDK"} ```bash language="js" title="npm" tab="js-1" npm install @workos-inc/node ``` ```bash language="js" title="Yarn" tab="js-2" yarn add @workos-inc/node ``` ```bash language="ruby" title="Terminal" tab="ruby-5" gem install workos ``` ```rb language="ruby" title="Bundler" tab="ruby-6" gem "workos" ``` ```bash language="python" pip install workos ``` ```bash language="go" go get github.com/workos/workos-go/v10 ``` ```bash language="php" composer require workos/workos-php ``` ```bash language="laravel" composer require workos/workos-php-laravel ``` ```xml language="java" title="Maven" tab="java-3" com.workos workos {version} ``` ```groovy language="java" title="Gradle" tab="java-4" dependencies { implementation 'com.workos:workos:VERSION' } ``` ```bash language="dotnet" nuget install WorkOS.net ``` ```elixir language="elixir" def deps do [{:workos, "~> 3.1"}] end ``` ```bash language="rust" cargo add workos ``` ::: ### Set secrets To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences. ```plain title="Environment variables" WORKOS_API_KEY='sk_example_123456789' WORKOS_CLIENT_ID='client_123456789' ``` ### Create a new organization Each Admin Portal session is scoped to a specific organization resource, meaning a session is only capable of managing a connection that belongs to its associated organization. Organizations may only have one connection. For every customer in your application that would like access to the Admin Portal, you must create an organization and maintain a reference to its ID. > Create an organization when onboarding a new customer. :::code-group{title="Create an organization"} ```ts language="js" title="Next.js" tab="js-1" import type { NextApiRequest, NextApiResponse } from 'next'; import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS(process.env.WORKOS_API_KEY); const clientId = process.env.WORKOS_CLIENT_ID; export default async (req: NextApiRequest, res: NextApiResponse) => { if (req.method === 'POST') { const organizationName = 'Example Organization'; const organizationDomains = [ { domain: 'foo-corp.com', state: 'pending', }, ]; const organization = await workos.organizations.createOrganization({ name: organizationName, domainData: organizationDomains, }); // You should persist `organization.id` since it will be needed // to generate a Portal Link. // Provision additional Enterprise-tier resources. } }; ``` ```js language="js" title="Express" tab="js-2" const express = require('express'); const { WorkOS } = require('@workos-inc/node'); const app = express(); const workos = new WorkOS(process.env.WORKOS_API_KEY); app.post('/provision-enterprise', async (_req, res) => { const organizationName = 'Example Organization'; const organizationDomains = [ { domain: 'foo-corp.com', state: 'pending', }, ]; const organization = await workos.organizations.createOrganization({ name: organizationName, domainData: organizationDomains, }); // You should persist `organization.id` since it will be needed // to generate a Portal Link. // Provision additional Enterprise-tier resources. }); ``` ```rb language="ruby" title="Rails" tab="ruby-3" require "workos" WORKOS = WorkOS::Client.new(api_key: ENV["WORKOS_API_KEY"]) def provision_enterprise organization_name = "Example Organization" organization_domains = [ { domain: "foo-corp.com", state: "pending" } ] organization = WORKOS.organizations.create_organization( name: organization_name, domain_data: organization_domains ) # You should persist `organization.id` since it will be needed # to generate a Portal Link. # Provision additional Enterprise-tier resources. end ``` ```rb language="ruby" title="Sinatra" tab="ruby-4" require "sinatra" require "workos" workos = WorkOS::Client.new(api_key: ENV["WORKOS_API_KEY"]) post "/provision-enterprise" do organization_name = "Example Organization" organization_domains = [ { domain: "foo-corp.com", state: "pending" } ] organization = workos.organizations.create_organization( name: organization_name, domain_data: organization_domains ) # You should persist `organization.id` since it will be needed # to generate a Portal Link. # Provision additional Enterprise-tier resources. end ``` ```py language="python" title="Django" tab="python-5" from workos import WorkOSClient workos_client = WorkOSClient( api_key="sk_example_123456789", client_id="client_123456789" ) def provision_enterprise(): organization_name = "Example Organization" organization_domains = [ { "domain": "foo-corp.com", "state": "pending", } ] organization = workos_client.organizations.create_organization( name=organization_name, domain_data=organization_domains ) # You should persist `organization['id']` since it will be needed # to generate a Portal Link. # Provision additional Enterprise-tier resources. ``` ```py language="python" title="Flask" tab="python-6" from flask import Flask from workos import WorkOSClient workos_client = WorkOSClient( api_key="sk_example_123456789", client_id="client_123456789" ) app = Flask(__name__) @app.route("/provision-enterprise", methods=["POST"]) def provision_enterprise(): organization_name = "Example Organization" organization_domains = [ { "domain": "foo-corp.com", "state": "pending", } ] organization = workos_client.organizations.create_organization( name=organization_name, domain_data=organization_domains ) # You should persist `organization['id']` since it will be needed # to generate a Portal Link. # Provision additional Enterprise-tier resources. ``` ```go language="go" package main import ( "context" "github.com/workos/workos-go/v10" ) func main() { client := workos.NewClient("sk_example_123456789") _, err := client.Organizations().Create(context.Background(), &workos.OrganizationsCreateParams{ Name: "Foo Corp", }) if err != nil { // Handle the error according to your application's needs. return } } ``` ```php language="php" organizations()->createOrganization(name: "Foo Corp"); ``` ```php language="laravel" createOrganization( name: $organizationName, domainData: $organizationDomains, ); // You should persist `$organization->id` since it will be needed // to generate a Portal Link. // Provision additional Enterprise-tier resources. }); ``` ```java language="java" import com.workos.WorkOS; import com.workos.organizations.OrganizationsApi.CreateOrganizationOptions; WorkOS workos = new WorkOS("sk_example_123456789"); CreateOrganizationOptions options = CreateOrganizationOptions.builder().name("Foo Corp").build(); workos.organizations.createOrganization(options); ``` ```cs language="dotnet" using WorkOS; var client = new WorkOSClient(new WorkOSOptions { ApiKey = "sk_example_123456789", ClientId = "client_123456789", }); await client.Organizations.CreateAsync(new OrganizationsCreateOptions { Name = "Foo Corp", }); ``` ```elixir language="elixir" client = WorkOS.client( api_key: "sk_example_123456789", client_id: "client_123456789" ) WorkOS.Organizations.create_organization(client, %{ name: "Foo Corp" }) ``` ```rust language="rust" // workos:manual - target the current Rust SDK request model use workos::organizations::CreateOrganizationParams; use workos::{Client, OrganizationInput}; #[tokio::main] async fn main() -> Result<(), workos::Error> { let client = Client::builder() .api_key("sk_example_123456789") .client_id("client_123456789") .build(); let _organization = client .organizations() .create_organization(CreateOrganizationParams::new(OrganizationInput { name: "Foo Corp".into(), allow_profiles_outside_organization: None, domains: None, domain_data: None, metadata: None, external_id: None, })) .await?; Ok(()) } ``` ::: ### Redirect IT contacts to the Admin Portal A Portal link is your enterprise user's gateway to accessing the Admin Portal, where they can set up and manage resources scoped to their organization. To generate a Portal link using the API, you must provide the organization ID and specify one of the following intents: [`sso`](https://workos.com/docs/admin-portal/c-using-admin-portal/managing-sso-connections), [`dsync`](https://workos.com/docs/admin-portal/c-using-admin-portal/managing-directories), [`audit_logs`](https://workos.com/docs/audit-logs/admin-portal/creating-admin-portal-link), [`log_streams`](https://workos.com/docs/audit-logs/log-streams/admin-portal), [`domain_verification`](https://workos.com/docs/domain-verification/admin-portal-domain-verification), or [`certificate_renewal`](https://workos.com/docs/sso/signing-certificates/saml-response-signing-certificate/renewing-certificates). For security reasons, Portal links expire 5 minutes after they're created, so we recommend redirecting users immediately (i.e. don't email the user Portal links). > The endpoint that redirects a user to the Admin Portal should be guarded by auth in your application and only available to IT contacts. :::code-group{title="Redirect to Admin Portal"} ```ts language="js" title="Next.js" tab="js-1" import type { NextApiRequest, NextApiResponse } from 'next'; import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS(process.env.WORKOS_API_KEY); export default async (_req: NextApiRequest, res: NextApiResponse) => { // The ID of the organization to start an Admin Portal session for const organizationId = 'org_123'; const { link } = await workos.adminPortal.generateLink({ organization: organizationId, intent: 'sso', }); res.redirect(link); }; ``` ```js language="js" title="Express" tab="js-2" const express = require('express'); const { WorkOS } = require('@workos-inc/node'); const app = express(); const workos = new WorkOS(process.env.WORKOS_API_KEY); app.get('/admin-portal', async (_req, res) => { // The ID of the organization to start an Admin Portal session for const organizationId = 'org_123'; const { link } = await workos.adminPortal.generateLink({ organization: organizationId, intent: 'sso', }); res.redirect(link); }); ``` ```rb language="ruby" title="Rails" tab="ruby-3" require "workos" WORKOS = WorkOS::Client.new(api_key: ENV["WORKOS_API_KEY"]) def admin_portal # The ID of the organization to start an Admin Portal session for organization_id = "org_123" link = WORKOS.admin_portal.generate_link( organization: organization_id, intent: "sso" ) redirect_to link end ``` ```rb language="ruby" title="Sinatra" tab="ruby-4" require "sinatra" require "workos" workos = WorkOS::Client.new(api_key: ENV["WORKOS_API_KEY"]) get "/admin-portal" do # The ID of the organization to start an Admin Portal session for organization_id = "org_123" link = workos.admin_portal.generate_link( organization: organization_id, intent: "sso" ) redirect link end ``` ```py language="python" title="Django" tab="python-5" from django import redirect from workos import WorkOSClient workos_client = WorkOSClient( api_key="sk_example_123456789", client_id="client_123456789" ) def admin_portal(): organization_id = ( "org_123" # The ID of the organization to start an Admin Portal session for ) portal_link = workos_client.admin_portal.generate_link( organization=organization_id, intent="sso" ) return redirect(portal_link.link) ``` ```py language="python" title="Flask" tab="python-6" from flask import Flask, redirect from workos import WorkOSClient workos_client = WorkOSClient( api_key="sk_example_123456789", client_id="client_123456789" ) app = Flask(__name__) @app.route("/admin-portal") def admin_portal(): organization_id = ( "org_123" # The ID of the organization to start an Admin Portal session for ) portal_link = workos_client.admin_portal.generate_link( organization=organization_id, intent="sso" ) return redirect(portal_link.link) ``` ```go language="go" // workos:manual - preserve the SSO intent and generated link package main import ( "context" "fmt" "github.com/workos/workos-go/v10" ) func main() { client := workos.NewClient("sk_example_123456789") portalLink, err := client.AdminPortal().GenerateLink(context.Background(), &workos.AdminPortalGenerateLinkParams{ Organization: "org_01EHZNVPK3SFK441A1RGBFSHRT", Intent: workos.Ptr(workos.GenerateLinkIntentSSO), }) if err != nil { // Handle the error according to your application's needs. return } // Redirect the IT contact to this URL. fmt.Println(portalLink.Link) } ``` ```php language="php" adminPortal() ->generateLink( organization: "org_01EHZNVPK3SFK441A1RGBFSHRT", intent: GenerateLinkIntent::SSO, ); header("Location: {$portalLink->link}", true, 302); ``` ```php language="laravel" generateLink( organization: $organizationId, intent: GenerateLinkIntent::SSO, ); return redirect($portalLink->link); }); ``` ```java language="java" // workos:manual - preserve the SSO intent and generated link import com.workos.WorkOS; import com.workos.models.PortalLinkResponse; import com.workos.types.GenerateLinkIntent; WorkOS workos = WorkOS.builder().apiKey("sk_example_123456789").build(); PortalLinkResponse portalLink = workos.getAdminPortal().generateLink( "org_01EHZNVPK3SFK441A1RGBFSHRT", null, null, GenerateLinkIntent.SSO); // Redirect the IT contact to portalLink.getLink(). ``` ```cs language="dotnet" // workos:manual - preserve the SSO intent and generated link using WorkOS; var client = new WorkOSClient(new WorkOSOptions { ApiKey = "sk_example_123456789", ClientId = "client_123456789", }); var portalLink = await client.AdminPortal.GenerateLinkAsync(new AdminPortalGenerateLinkOptions { Organization = "org_01EHZNVPK3SFK441A1RGBFSHRT", Intent = GenerateLinkIntent.SSO, }); // Redirect the IT contact to portalLink.Link. ``` ```elixir language="elixir" # workos:manual - preserve the SSO intent and generated link client = WorkOS.client( api_key: "sk_example_123456789", client_id: "client_123456789" ) {:ok, portal_link} = WorkOS.AdminPortal.generate_link(client, %{ organization: "org_01EHZNVPK3SFK441A1RGBFSHRT", intent: "sso" }) # Redirect the browser to this URL. portal_link.link ``` ```rust language="rust" // workos:manual - preserve the SSO intent and generated link use workos::admin_portal::GenerateLinkParams; use workos::{Client, GenerateLink, GenerateLinkIntent}; #[tokio::main] async fn main() -> Result<(), workos::Error> { let client = Client::builder() .api_key("sk_example_123456789") .client_id("client_123456789") .build(); let portal_link = client .admin_portal() .generate_link(GenerateLinkParams::new(GenerateLink { organization: "org_01EHZNVPK3SFK441A1RGBFSHRT".into(), intent: Some(GenerateLinkIntent::SSO), return_url: None, success_url: None, it_contact_emails: None, })) .await?; // Redirect the IT contact to this URL. println!("{}", portal_link.link); Ok(()) } ``` ::: The optional `return_url` parameter controls where an admin is sent when they click your logo. The optional `success_url` parameter controls where an admin goes after setup. Values set when [generating a Portal link](https://workos.com/docs/reference/admin-portal/portal-link/generate) override the defaults configured on the [Admin Portal](https://dashboard.workos.com/admin-portal) page in the dashboard. ### Add IT contacts programmatically When generating a Portal link via the API, emails can be added as IT contacts for the organization at the same time by passing the optional `it_contact_emails` parameter. This mirrors the behavior of the "Invite IT contact" flow in the WorkOS dashboard. IT contacts receive future organization notifications, such as alerts for expiring SSO certificates. ```bash title="Generate a Portal link and add IT contacts" curl --request POST \ --url "https://api.workos.com/portal/generate_link" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d '{ "organization": "org_01EHZNVPK3SFK441A1RGBFSHRT", "intent": "sso", "it_contact_emails": ["it-contact@example.com", "it-lead@example.com"] }' ``` Any email that isn't already an IT contact for the organization will be added; existing IT contacts remain unchanged, so the same call can be made repeatedly with the full list of contacts without creating duplicates. Email matching is case-insensitive. An organization can have up to 20 IT contacts at a time. A request that would exceed this limit is rejected and no IT contacts from the request are created. Invalid email addresses are rejected without creating any IT contacts. Adding an email via `it_contact_emails` does not restrict who can use the Portal link, and it does not send a notification to the IT contact. The Portal link must still be delivered by the calling application—typically by redirecting the current authenticated user immediately. See the [Generate a Portal Link reference](https://workos.com/docs/reference/admin-portal/portal-link/generate) for the full request schema. ### IT contact email collection During Admin Portal setup for SSO and Directory Sync, you can require an IT contact email. That address receives alerts such as certificate expiration warnings and connection errors. New environments have this setting enabled. Environments created before the feature shipped need to enable it on the [Admin Portal](https://dashboard.workos.com/admin-portal) page.  When the setting is enabled, Admin Portal setup includes a required step to collect an IT contact email if the organization has no IT contact yet. When it is disabled, the step is skipped.  > By default, these notifications are sent from a WorkOS-branded address. To customize the sender, configure a [custom email domain](https://workos.com/docs/custom-domains/email) or [custom email provider](https://workos.com/docs/authkit/custom-email-providers). ## (C) Using Admin Portal In this guide, we'll review some of the features of Admin Portal from an IT contact's perspective. ### Verifying a domain In the Admin Portal [Domain Verification](https://workos.com/docs/domain-verification/admin-portal-domain-verification) flow, you can view instructions on adding a DNS TXT record to prove ownership of your organization's domain(s). > Unless an organization [allows any domain](https://workos.com/docs/sso/domains/allowing-any-domain), a verified domain is required in order to activate SSO. Domains can also be [manually verified](https://workos.com/docs/authkit/domain-verification/self-serve-domain-verification) outside of the self-serve Admin Portal flow if the IT contact has already proven domain ownership in another context. ### Managing SSO connections On the Admin Portal SSO screen, you can view the identity provider details and connection status, metadata configuration details, and a list of recent connection sessions. You may test your SSO connection from the Admin Portal by using the "Test sign-in" button.  You may also edit your metadata configuration from the Admin Portal.  The Sessions section displays a list of recent sessions by timestamp, and can be sorted by `state`.  Click on a session in the list to see session details, such as the request made to the IdP, and the response.  To delete an SSO connection, select "Delete connection" in the Danger zone, enter `DELETE CONNECTION`, and follow the prompts. This permanently removes the connection's single sign-on configuration and sign-in records from your team and cannot be undone. Your identity provider and its users are not affected. ### Managing directories On the Admin Portal Directory Sync screen, you can view the directory provider details and connection status, user and group counts, and last sync time. To delete a directory, select "Delete directory" in the Danger zone, enter `DELETE DIRECTORY`, and follow any provider-specific cleanup instructions. This permanently removes synced users, groups, and settings from your team and cannot be undone. Your source directory and its users are not affected. You may also view and edit the attribute map from the synced directory by clicking "Edit Attribute Map".  If you wish to update the groups that are being synced, select "Edit groups sync" and follow the prompts on the next page.  You can also view a complete list of users from all selected groups in your synced directory.