Setup guide

Connect Okta to Artillo

Let your people sign in to Artillo with their Okta account, give admins their role from an Okta group, and create, update and deactivate Artillo accounts automatically as people join, move and leave.

Before you start

You need to be an admin in both places: an Artillo admin for your organization, and an Okta admin who can create app integrations.

Throughout this guide, your-org stands for your Artillo address (the part before .artillo.com). Artillo shows every URL you need, already filled in, under Admin → Settings → Single Sign-On (SSO).

Use SAML for sign-in unless you have a reason to prefer OpenID Connect. The SAML app is also where you switch on SCIM provisioning, so one Okta app does everything.

1. SAML sign-in

In Artillo

Go to Admin → Settings → Single Sign-On (SSO) and choose Add SSO Provider.
For the provider, pick SAML 2.0 (any identity provider). Keep this page open: it shows the values Okta needs.

In Okta

Go to Applications → Applications → Create App Integration, choose SAML 2.0, and name the app Artillo.
On Configure SAML, enter:

Single sign-on URL	`https://api.artillo.com/login/saml2/sso/your-org-saml` (Artillo's “Reply URL”). Leave Use this for Recipient URL and Destination URL ticked.
Audience URI (SP Entity ID)	`https://api.artillo.com/saml2/metadata/your-org-saml` (Artillo's “Entity ID”)
Name ID format	`EmailAddress`
Application username	`Email`

Under Attribute Statements, add:

`email`	`user.email` (required)
`firstName`	`user.firstName`
`lastName`	`user.lastName`
`department`	`user.department` (optional: fills in the person's department)
`title`	`user.title` (optional: job title)
`managerEmail`	the manager's email, for example `user.managerId` if your directory keeps it there (optional: builds reporting lines for manager views)

Under Group Attribute Statements, add groups with a filter that matches the groups you'll map to Artillo roles, for example Starts with Artillo. Skip this if you don't want roles to come from Okta.

Finish the wizard (Okta asks whether this is an internal app; either answer works).
On the app's Sign On tab, copy the Metadata URL.
On the Assignments tab, assign the people or groups who should use Artillo.

Back in Artillo

Paste Okta's metadata URL into IdP metadata URL.
Set Email domain to your company's domain, for example acme.com. People with that domain are sent to Okta when they sign in.
Leave Require SSO for this domain on if people with your domain should only sign in through Okta (their Artillo passwords stop working). Turn it off while you test if you want a fallback.
Save.

Artillo re-reads Okta's metadata URL every day, so when Okta rotates its signing certificate, nothing breaks and you don't need to do anything.

Test it

Open https://your-org.artillo.com, enter the email of someone assigned to the app and choose Continue with your company account. After signing in at Okta they land on their Artillo dashboard. The Artillo tile on the Okta dashboard works too.

The first time someone signs in, Artillo creates their account if their email domain is your SSO email domain or one of your organization's allowed domains, and you have seats available. Existing accounts with the same email are linked, so people keep their progress.

2. Single logout (optional)

With single logout, signing out of Artillo also ends the person's Okta session (and so their other Okta apps' sessions). Signing out at Okta always signs them out of Artillo too, once this is set up.

In Artillo

In your SAML provider, download Artillo's certificate (Download .crt) and note the Logout URL.

In Okta

Edit the app's SAML settings, open Show Advanced Settings, tick Enable Single Logout and enter:

Single Logout URL	`https://api.artillo.com/logout/saml2/slo/your-org-saml`
SP Issuer	`https://api.artillo.com/saml2/metadata/your-org-saml`
Signature Certificate	Upload the .crt file from Artillo

Back in Artillo

Tick Also sign people out of your identity provider and save. Saving also re-reads Okta's metadata, which now includes Okta's logout address.

If you ever choose Replace key and certificate in Artillo, upload the new certificate to Okta straight away, or logout requests will be rejected.

3. Roles from Okta groups

You can let Okta decide who is an Artillo admin. Create an Okta group such as Artillo-Admins, add your admins to it, and make sure the group filter from step 1 includes it.

In Artillo

Under Roles from your identity provider's groups, add the group's name exactly as it appears in Okta (Artillo-Admins) and choose Admin.

People Okta creates in Artillo start as Employees. From then on, each sign-in and each SCIM update sets the person's role from their groups:

Someone in a mapped group gets that role; if they're in several, the highest role wins.
Someone in none of the mapped groups becomes an Employee, so removing a person from Artillo-Admins in Okta removes their admin rights.
Artillo never demotes your last remaining admin, so you can't lock yourself out.

Without SCIM, a role change takes effect the next time the person signs in. With SCIM group push (below), it takes effect within seconds.

4. Provisioning with SCIM

SCIM lets Okta manage Artillo accounts for you: assigning someone to the Artillo app creates their account, profile changes are copied over, and unassigning or deactivating them in Okta deactivates them in Artillo. Deactivated people can't sign in, but their training history and certificates are kept.

In Artillo

Under SCIM Provisioning, choose Generate Token. Copy the token now: it's shown only once.
Note the SCIM Base URL: https://api.artillo.com/scim/v2.

In Okta (the same Artillo app)

On the General tab, edit App Settings, set Provisioning to SCIM and save. A Provisioning tab appears.
On Provisioning → Integration, choose Edit and enter:

SCIM connector base URL	`https://api.artillo.com/scim/v2`
Unique identifier field for users	`userName`
Supported provisioning actions	Push New Users, Push Profile Updates and Push Groups
Authentication Mode	HTTP Header
Authorization	the token from Artillo (with or without `Bearer` in front)

Choose Test Connector Configuration; Okta should report success. Then save.
On Provisioning → To App, choose Edit and enable Create Users, Update User Attributes and Deactivate Users. Save.
If you map roles from groups, open the Push Groups tab, choose Push Groups → Find groups by name, pick Artillo-Admins and save.

What happens next:

Assign someone to the app	Their Artillo account is created (or their existing account is linked by email)
Add them to a pushed, mapped group	They get that role, for example Admin
Remove them from the group	They lose that role
Change their name, department or job title	Artillo is updated
Unassign or deactivate them	Their Artillo account is deactivated and signed out
Assign them again	Their account is reactivated with its history

In our tests each of these reached Artillo within about 15 seconds.

Treat the SCIM token like a password. If it leaks, choose Regenerate Token in Artillo and paste the new one into Okta; the old one stops working immediately.

Alternative: OpenID Connect

If you prefer OIDC for sign-in, set it up instead of SAML (SCIM still needs an app with provisioning, as above).

In Okta

Create an app integration: OIDC – OpenID Connect, Web Application, grant type Authorization Code.
Set the Sign-in redirect URI to Artillo's Redirect URI: https://api.artillo.com/login/oauth2/code/your-org-okta. Assign your people.
For roles from groups, use an authorization server that sends groups: in Security → API → Authorization Servers → default → Claims, add a claim named groups, included in the ID Token Always, value type Groups, filter Starts with Artillo. Make sure an access policy on that server allows the Artillo app.

In Artillo

Add an SSO provider of type Okta.
Set Issuer URL to https://your-okta-domain/oauth2/default (orhttps://your-okta-domain if you don't need groups), and paste the app's Client ID and Client Secret.
Set the email domain and save. Use Test Connection to check the issuer.

Troubleshooting

“The SAML assertion has no email address”	Add the `email` attribute statement (step 1), or set Name ID format to EmailAddress.
Someone can’t sign in the first time	Their email domain must be your SSO email domain or one of your allowed domains (Admin → Settings), and you need a free seat.
A role didn’t change	The Artillo mapping must match the Okta group name exactly, and the group must pass the `groups` filter. Without SCIM, the change applies at the next sign-in.
Okta: “Error authenticating … SCIM Bearer token required”	The Authorization field is empty or has extra text. Paste the token again, or generate a new one in Artillo.
Okta: “Invalid SCIM token”	The token was regenerated or revoked in Artillo. Generate a new one and update Okta.
Sign-in fails after Okta changed its certificate	Only happens with pasted metadata XML. Switch to the metadata URL so Artillo picks up new certificates by itself.

Still stuck? Contact us with the time of the failed attempt and the email involved, and we'll look at it with you.

Setup guide

Connect Okta to Artillo

Let your people sign in to Artillo with their Okta account, give admins their role from an Okta group, and create, update and deactivate Artillo accounts automatically as people join, move and leave.

Before you start

You need to be an admin in both places: an Artillo admin for your organization, and an Okta admin who can create app integrations.

Use SAML for sign-in unless you have a reason to prefer OpenID Connect. The SAML app is also where you switch on SCIM provisioning, so one Okta app does everything.

1. SAML sign-in

In Artillo

Go to Admin → Settings → Single Sign-On (SSO) and choose Add SSO Provider.
For the provider, pick SAML 2.0 (any identity provider). Keep this page open: it shows the values Okta needs.

In Okta

Go to Applications → Applications → Create App Integration, choose SAML 2.0, and name the app Artillo.
On Configure SAML, enter:

Single sign-on URL	`https://api.artillo.com/login/saml2/sso/your-org-saml` (Artillo's “Reply URL”). Leave Use this for Recipient URL and Destination URL ticked.
Audience URI (SP Entity ID)	`https://api.artillo.com/saml2/metadata/your-org-saml` (Artillo's “Entity ID”)
Name ID format	`EmailAddress`
Application username	`Email`

Under Attribute Statements, add:

`email`	`user.email` (required)
`firstName`	`user.firstName`
`lastName`	`user.lastName`
`department`	`user.department` (optional: fills in the person's department)
`title`	`user.title` (optional: job title)
`managerEmail`	the manager's email, for example `user.managerId` if your directory keeps it there (optional: builds reporting lines for manager views)

Finish the wizard (Okta asks whether this is an internal app; either answer works).
On the app's Sign On tab, copy the Metadata URL.
On the Assignments tab, assign the people or groups who should use Artillo.

Back in Artillo

Paste Okta's metadata URL into IdP metadata URL.
Set Email domain to your company's domain, for example acme.com. People with that domain are sent to Okta when they sign in.
Leave Require SSO for this domain on if people with your domain should only sign in through Okta (their Artillo passwords stop working). Turn it off while you test if you want a fallback.
Save.

Artillo re-reads Okta's metadata URL every day, so when Okta rotates its signing certificate, nothing breaks and you don't need to do anything.

Test it

2. Single logout (optional)

With single logout, signing out of Artillo also ends the person's Okta session (and so their other Okta apps' sessions). Signing out at Okta always signs them out of Artillo too, once this is set up.

In Artillo

In your SAML provider, download Artillo's certificate (Download .crt) and note the Logout URL.

In Okta

Edit the app's SAML settings, open Show Advanced Settings, tick Enable Single Logout and enter:

Single Logout URL	`https://api.artillo.com/logout/saml2/slo/your-org-saml`
SP Issuer	`https://api.artillo.com/saml2/metadata/your-org-saml`
Signature Certificate	Upload the .crt file from Artillo

Back in Artillo

Tick Also sign people out of your identity provider and save. Saving also re-reads Okta's metadata, which now includes Okta's logout address.

If you ever choose Replace key and certificate in Artillo, upload the new certificate to Okta straight away, or logout requests will be rejected.

3. Roles from Okta groups

You can let Okta decide who is an Artillo admin. Create an Okta group such as Artillo-Admins, add your admins to it, and make sure the group filter from step 1 includes it.

In Artillo

Under Roles from your identity provider's groups, add the group's name exactly as it appears in Okta (Artillo-Admins) and choose Admin.

People Okta creates in Artillo start as Employees. From then on, each sign-in and each SCIM update sets the person's role from their groups:

Someone in a mapped group gets that role; if they're in several, the highest role wins.
Someone in none of the mapped groups becomes an Employee, so removing a person from Artillo-Admins in Okta removes their admin rights.
Artillo never demotes your last remaining admin, so you can't lock yourself out.

Without SCIM, a role change takes effect the next time the person signs in. With SCIM group push (below), it takes effect within seconds.

4. Provisioning with SCIM

In Artillo

Under SCIM Provisioning, choose Generate Token. Copy the token now: it's shown only once.
Note the SCIM Base URL: https://api.artillo.com/scim/v2.

In Okta (the same Artillo app)

On the General tab, edit App Settings, set Provisioning to SCIM and save. A Provisioning tab appears.
On Provisioning → Integration, choose Edit and enter:

SCIM connector base URL	`https://api.artillo.com/scim/v2`
Unique identifier field for users	`userName`
Supported provisioning actions	Push New Users, Push Profile Updates and Push Groups
Authentication Mode	HTTP Header
Authorization	the token from Artillo (with or without `Bearer` in front)

Choose Test Connector Configuration; Okta should report success. Then save.
On Provisioning → To App, choose Edit and enable Create Users, Update User Attributes and Deactivate Users. Save.
If you map roles from groups, open the Push Groups tab, choose Push Groups → Find groups by name, pick Artillo-Admins and save.

What happens next:

Assign someone to the app	Their Artillo account is created (or their existing account is linked by email)
Add them to a pushed, mapped group	They get that role, for example Admin
Remove them from the group	They lose that role
Change their name, department or job title	Artillo is updated
Unassign or deactivate them	Their Artillo account is deactivated and signed out
Assign them again	Their account is reactivated with its history

In our tests each of these reached Artillo within about 15 seconds.

Treat the SCIM token like a password. If it leaks, choose Regenerate Token in Artillo and paste the new one into Okta; the old one stops working immediately.

Alternative: OpenID Connect

If you prefer OIDC for sign-in, set it up instead of SAML (SCIM still needs an app with provisioning, as above).

In Okta

Create an app integration: OIDC – OpenID Connect, Web Application, grant type Authorization Code.
Set the Sign-in redirect URI to Artillo's Redirect URI: https://api.artillo.com/login/oauth2/code/your-org-okta. Assign your people.
For roles from groups, use an authorization server that sends groups: in Security → API → Authorization Servers → default → Claims, add a claim named groups, included in the ID Token Always, value type Groups, filter Starts with Artillo. Make sure an access policy on that server allows the Artillo app.

In Artillo

Add an SSO provider of type Okta.
Set Issuer URL to https://your-okta-domain/oauth2/default (orhttps://your-okta-domain if you don't need groups), and paste the app's Client ID and Client Secret.
Set the email domain and save. Use Test Connection to check the issuer.

Troubleshooting

“The SAML assertion has no email address”	Add the `email` attribute statement (step 1), or set Name ID format to EmailAddress.
Someone can’t sign in the first time	Their email domain must be your SSO email domain or one of your allowed domains (Admin → Settings), and you need a free seat.
A role didn’t change	The Artillo mapping must match the Okta group name exactly, and the group must pass the `groups` filter. Without SCIM, the change applies at the next sign-in.
Okta: “Error authenticating … SCIM Bearer token required”	The Authorization field is empty or has extra text. Paste the token again, or generate a new one in Artillo.
Okta: “Invalid SCIM token”	The token was regenerated or revoked in Artillo. Generate a new one and update Okta.
Sign-in fails after Okta changed its certificate	Only happens with pasted metadata XML. Switch to the metadata URL so Artillo picks up new certificates by itself.

Still stuck? Contact us with the time of the failed attempt and the email involved, and we'll look at it with you.