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:

list_custom_domains

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

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.
dnsRecords	array
domain	string	Custom domain name (example: login.example.com)
publicCertificate	object	Certificate metadata for the domain
validationStatus	string	Status of the domain (example: VERIFIED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_custom_domains	select	subdomain		Lists all verified custom domains for the org
get_custom_domain	select	subdomain		Retrieves a custom domain by domainId
create_custom_domain	insert	subdomain, data__certificateSourceType, data__domain		Creates your custom domain
replace_custom_domain	replace	subdomain, data__brandId		Replaces a custom domain's brand
delete_custom_domain	delete	subdomain		Deletes a custom domain by domainId
upsert_certificate	exec	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	subdomain		Verifies the custom domain and validity of DNS records by domainId. 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.

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
subdomain	string	The domain of your organization. This can be a provided subdomain of an official okta domain (okta.com, oktapreview.com, etc) or one of your configured custom domains. (default: my-org)

SELECT examples

list_custom_domains

Lists all verified custom domains for the org

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

get_custom_domain

Retrieves a custom domain by domainId

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

INSERT examples

create_custom_domain

Creates your custom domain

INSERT INTO okta.domains.custom_domains (
data__certificateSourceType,
data__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: string
      description: Required parameter for the custom_domains resource.
    - name: certificateSourceType
      value: string
      description: >
        Certificate source type that indicates whether the certificate is provided by the user or Okta.
        
      valid_values: ['MANUAL', 'OKTA_MANAGED']
    - name: domain
      value: string
      description: >
        Custom domain name
        

REPLACE examples

replace_custom_domain

Replaces a custom domain's brand

REPLACE okta.domains.custom_domains
SET 
data__brandId = '{{ brandId }}'
WHERE 
subdomain = '{{ subdomain }}' --required
AND data__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 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 
@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. 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.

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