custom_domains

Creates, updates, deletes, gets or lists a custom_domains resource.

Overview

Name	custom_domains
Type	Resource
Id	okta.domains.custom_domains

Fields

The following fields are returned by SELECT queries:

get_custom_domain

Name	Datatype	Description
id	string	Unique ID of the domain (example: OcDz6iRyjkaCTXkdo0g3)
_links	object	Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
brandId	string	The ID number of the brand (example: bndul904tTZ6kWVhP0g3)
certificateSourceType	string	Certificate source type that indicates whether the certificate is provided by the user or Okta. (MANUAL, OKTA_MANAGED)
dnsRecords	array
domain	string	Custom domain name (example: login.example.com)
publicCertificate	object	Certificate metadata for the domain
validationStatus	string	Status of the domain (COMPLETED, IN_PROGRESS, NOT_STARTED, VERIFIED) (example: VERIFIED)

list_custom_domains

Name	Datatype	Description
domains	array	Each element of the array defines an individual domain

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_custom_domain	select	domainId, subdomain		Retrieves a custom domain by domainId
list_custom_domains	select	subdomain		Lists all verified custom domains for the org
create_custom_domain	insert	subdomain, certificateSourceType, domain		Creates your custom domain
replace_custom_domain	replace	domainId, subdomain, brandId		Replaces a custom domain's brand
delete_custom_domain	delete	domainId, subdomain		Deletes a custom domain by domainId
upsert_certificate	exec	domainId, subdomain, certificate, certificateChain, privateKey, type		Upserts (creates or renews) the MANUAL certificate for the custom domain > Notes: > * If the existing certificateSourceType is OKTA_MANAGED, this operation changes the source type to MANUAL. Okta no longer manages and renews certificates for this domain after you provide a user-managed certificate. > * Okta supports TLS certificates and private keys that are PEM-encoded and 2048, 3072, or 4096 bits. See the Custom domain guide for more details.
verify_domain	exec	domainId, subdomain		Verifies the custom domain and validity of DNS records by domainId. Verify your custom domain to confirm that you own or control the domain and that you have properly configured the required DNS records. Furthermore, if the certificateSourceType in the domain is OKTA_MANAGED, then an attempt is made to obtain and install a certificate. After a certificate is obtained and installed by Okta, Okta manages the certificate including certificate renewal. Verify your custom domain after you've created it and after you've added your DNS records to your domain provider. Okta doesn't verify your domain automatically. You must use the API to verify your custom domain if you change your DNS records or if you encounter issues with domain validation. > Note: DNS record changes can take time to propagate. If you recently updated your DNS records, you may need to wait before verifying your custom domain. If you encounter issues with domain verification, double-check your DNS records and ensure that they're correctly configured. See Update your DNS records.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
domainId	string	id of the Domain
subdomain	string	(default: my-org)

SELECT examples

get_custom_domain

Retrieves a custom domain by domainId

SELECT
id,
_links,
brandId,
certificateSourceType,
dnsRecords,
domain,
publicCertificate,
validationStatus
FROM okta.domains.custom_domains
WHERE domainId = '{{ domainId }}' -- required
AND subdomain = '{{ subdomain }}' -- required
;

list_custom_domains

Lists all verified custom domains for the org

SELECT
domains
FROM okta.domains.custom_domains
WHERE subdomain = '{{ subdomain }}' -- required
;

INSERT examples

create_custom_domain

Creates your custom domain

INSERT INTO okta.domains.custom_domains (
certificateSourceType,
domain,
subdomain
)
SELECT 
'{{ certificateSourceType }}' /* required */,
'{{ domain }}' /* required */,
'{{ subdomain }}'
RETURNING
id,
_links,
brandId,
certificateSourceType,
dnsRecords,
domain,
publicCertificate,
validationStatus
;

Manifest

# Description fields are for documentation purposes
- name: custom_domains
props:
  - name: subdomain
    value: "{{ subdomain }}"
    description: Required parameter for the custom_domains resource.
  - name: certificateSourceType
    value: "{{ certificateSourceType }}"
    description: |
      Certificate source type that indicates whether the certificate is provided by the user or Okta.
    valid_values: ['MANUAL', 'OKTA_MANAGED']
  - name: domain
    value: "{{ domain }}"
    description: |
      Custom domain name
      > **Note:** You can't use the reserved `drapp.{yourOrgSubDomain}.okta.com` domain.

REPLACE examples

replace_custom_domain

Replaces a custom domain's brand

REPLACE okta.domains.custom_domains
SET 
brandId = '{{ brandId }}'
WHERE 
domainId = '{{ domainId }}' --required
AND subdomain = '{{ subdomain }}' --required
AND brandId = '{{ brandId }}' --required
RETURNING
id,
_links,
brandId,
certificateSourceType,
dnsRecords,
domain,
publicCertificate,
validationStatus;

DELETE examples

delete_custom_domain

Deletes a custom domain by domainId

DELETE FROM okta.domains.custom_domains
WHERE domainId = '{{ domainId }}' --required
AND subdomain = '{{ subdomain }}' --required
;

Lifecycle Methods

upsert_certificate

Upserts (creates or renews) the MANUAL certificate for the custom domain

> Notes:
> * If the existing certificateSourceType is OKTA_MANAGED, this operation changes the source type to MANUAL. Okta no longer manages and renews certificates for this domain after you provide a user-managed certificate.
> * Okta supports TLS certificates and private keys that are PEM-encoded and 2048, 3072, or 4096 bits. See the Custom domain guide for more details.

EXEC okta.domains.custom_domains.upsert_certificate 
@domainId='{{ domainId }}' --required, 
@subdomain='{{ subdomain }}' --required 
@@json=
'{
"certificate": "{{ certificate }}", 
"certificateChain": "{{ certificateChain }}", 
"privateKey": "{{ privateKey }}", 
"type": "{{ type }}"
}'
;

verify_domain

Verifies the custom domain and validity of DNS records by domainId. Verify your custom domain to confirm that you own or control the domain and that you have properly configured the required DNS records. Furthermore, if the certificateSourceType in the domain is OKTA_MANAGED, then an attempt is made to obtain and install a certificate. After a certificate is obtained and installed by Okta, Okta manages the certificate including certificate renewal.

Verify your custom domain after you've created it and after you've added your DNS records to your domain provider. Okta doesn't verify your domain automatically. You must use the API to verify your custom domain if you change your DNS records or if you encounter issues with domain validation.

> Note: DNS record changes can take time to propagate. If you recently updated your DNS records, you may need to wait before verifying your custom domain. If you encounter issues with domain verification, double-check your DNS records and ensure that they're correctly configured. See Update your DNS records.

EXEC okta.domains.custom_domains.verify_domain 
@domainId='{{ domainId }}' --required, 
@subdomain='{{ subdomain }}' --required
;