It is a ready-made Okta connection that links one Okta organization to another.

An Okta organization, usually shortened to org, is a separate Okta environment with its own web address, its own people, its own applications, and its own rules. Most companies have one. But many have two, three, or dozens. A company might keep a “production” org for real work and a “preview” org for testing. A group of companies that merged might each still have their own org. A large business might give each region or division its own.

Org2Org is the name of an integration in Okta’s application catalog that lets one org treat another org as if it were any other application. It does two big jobs:

Ten small ideas explain the whole subject.

How the pieces fit

In the source org, an administrator adds the Org2Org application and fills in the details of the target org. The administrator gives the source org a secret key for the target, chooses which people and groups to send, and decides how their information should be translated. From then on, the source org keeps the target org up to date and vouches for its people at sign-in.

Several honest, everyday reasons lead to a second org. Knowing them tells you what the connection must achieve.

One org sends; the other receives. Keeping that direction clear prevents most confusion.

The most common arrangement is a hub-and-spoke picture. The source org is the hub and holds the authoritative list of people. One or more target orgs are spokes. Information flows from the hub to each spoke. Sign-in trust flows the same way: spokes trust the hub.

flowchart TD
  HR["Authoritative people list - for example the HR system"] --> SRC["Source org - the hub"]
  SRC -- "Users and groups copied" --> T1["Target org A"]
  SRC -- "Users and groups copied" --> T2["Target org B"]
  SRC -- "Sign-in trust" --> T1
  SRC -- "Sign-in trust" --> T2
  T1 --> A1["Applications in org A"]
  T2 --> A2["Applications in org B"]
    

Why direction matters

In the basic setup, the target org receives people from the source org. It is not designed to send changes back. If someone edits a person’s details directly in the target org, the next update from the source may overwrite those edits, or the two orgs may drift apart. Decide in advance where each piece of information is allowed to be changed. This idea is called the source of truth.

A basic setup does the essentials well. Knowing the edges stops you from expecting the wrong things.

These two jobs are separate. You can use one without the other, but they work best together.

What happens if you use only one

If you set up sign-in trust without provisioning, the target org has nobody on its list, so the trusted visitor has no account to land in. Some setups can create the account on the spot, but this is easier to get wrong. If you set up provisioning without sign-in trust, the target org has the right people, but they still need separate passwords there. Most organizations want both.

Follow one person from the source org into the target org and see who trusts whom.

The sign-in trust uses a standard way of passing proof of identity called SAML (pronounced “sam-el”). In plain words, the source org writes a short digital note that says, “This is Priya, her email is such-and-such, I checked her myself just now.” The note is signed with a secret that only the source org holds, so the target can tell it is genuine. The target org checks the signature, trusts the note, and lets Priya in.

sequenceDiagram
  participant P as Person
  participant B as Browser
  participant S as Source org
  participant T as Target org
  P->>B: Click the target org tile
  B->>S: Ask the source org to sign the person in
  S->>S: Check the person's session and rules
  S->>B: Return a signed identity note
  B->>T: Present the signed note
  T->>T: Check the signature and the person's account
  T->>B: Create a session in the target org
  B->>P: Show the target org
    

Provisioning is a conversation between the two orgs, carried out by machines on behalf of administrators.

When someone is assigned to the Org2Org application in the source org, or when their information changes, the source org sends a request to the target org. The request uses the target org’s management interface, which is the same interface administrators and tools can use to manage users. The source org proves it has permission by presenting an API token created in the target org.

sequenceDiagram
  participant A as Administrator
  participant S as Source org
  participant T as Target org
  A->>S: Assign a person or group to the connection
  S->>S: Prepare the person details using the mapping
  S->>T: Request - create this user, with the API token
  T->>T: Check the token and permissions
  T->>T: Create the user
  T->>S: Confirm success
  Note over S,T: Later changes are sent the same way
  A->>S: Change the person details
  S->>T: Request - update this user
  A->>S: Remove the assignment
  S->>T: Request - deactivate this user
    

The three lifecycle actions

Most Org2Org troubles begin before anyone touches a setting. A little preparation saves days.

Here is the whole process in plain words. Screen names may differ, but the order of ideas stays the same.

The token is the key that opens the target org to the source org. Treat it like the master key to a building.

An API token is a long secret string. Anyone holding it can do whatever the token’s owner is allowed to do, without a password or a second factor. The source org stores the token and presents it with every request to the target org. That is convenient for automation, and dangerous if the token leaks.

Two orgs may name the same fact differently. The mapping is the dictionary between them.

Every person in an org has a profile: a set of facts such as first name, last name, email, username, title, department, manager, and phone. These facts are called attributes. The source org and the target org may both have an attribute for “department,” but one might call it department and the other division. The mapping tells the source org which of its facts to put into which of the target’s slots.

Questions to ask for each attribute

• Does the target truly need it, or are we copying it only because we can?
• Does it contain private information that should stay in the source org?
• Do both orgs allow the same values, or does the target have a stricter list?
• Can the target org also edit it, and if so, which version wins?

The target org must recognize that “Priya in the source” and “Priya in the target” are the same person.

When the source org sends a person to the target, the target must decide: is this a new person, or one that already exists? The usual clue is the username, which in Okta is typically an email-style address and must be unique within an org. If the same username already exists in the target, the connection can either match the existing person or fail with a conflict.

Groups save work, because access follows them. Sending them across is a major part of the connection.

In Okta, a group is a named collection of people, such as “Finance” or “Engineering.” Applications and policies are often assigned to groups rather than to individuals. Group push is the feature that creates matching groups in the target org and keeps their membership in step with the source.

flowchart LR
  subgraph SRCG ["Source org"]
    G1["Group: Finance"]
    U1["Priya"]
    U2["Arjun"]
    U1 --> G1
    U2 --> G1
  end
  subgraph TGTG ["Target org"]
    G2["Group: Finance - pushed copy"]
    U3["Priya - copy"]
    U4["Arjun - copy"]
    U3 --> G2
    U4 --> G2
  end
  G1 -- "Group push" --> G2
    

Cautions about groups

Assignment decides who is sent and who is trusted. Smaller scopes are safer scopes.

Only people and groups assigned to the Org2Org application in the source org are copied and allowed to sign in to the target through it. Assigning “Everyone” is quick but sends everyone, including people who have no business in the target. A careful administrator assigns by purpose.

When two copies of the same fact exist, they eventually disagree unless someone decides which one counts.

After provisioning begins, each person exists twice: once in the source and once in the target. The two records are supposed to match, but they can drift apart in several ways: an administrator edits the target directly, the target has local rules that change attributes, or an update fails and nobody notices.

A calm approach

Decide, attribute by attribute, who may change it. Write it in a short table that every administrator of both orgs can see. Then run a regular comparison that lists people who differ between the orgs, and fix differences at the source.

Every person’s life at work passes through three moments. Both orgs must follow each one.

People may begin their journey at either org. Both starting points should be planned.

When the person begins at the source, the process is called IdP-initiated sign-in, because the identity provider starts it. When they begin at the target, it is called SP-initiated, because the service provider starts it. The target org can be configured to treat the source as an identity provider and to route certain people, for example those with a company email domain, to the source automatically.

flowchart TD
  S1["Person opens the target address directly"] --> R{"Does a routing rule match this person?"}
  R -- Yes --> SRC["Redirect to the source org to sign in"]
  SRC --> BACK["Signed note returns to the target"]
  BACK --> IN["Person is in the target org"]
  R -- No --> LOC["Target's own sign-in page"]
    

When one org vouches for a person to another, the strength of the vouching matters.

Suppose the source org checks a password and a fingerprint, then vouches for the person to the target. The target accepts that note. If the source org’s sign-in was weak, for example a password alone, the target has inherited that weakness without knowing it. The strength of the chain is the strength of its weakest link.

Being signed in to the source does not mean being signed in to the target forever.

Each org has its own session rules. When a person arrives in the target through the trust, the target starts its own session with its own lifetime and idle limit. Ending the source session does not necessarily end the target session, and the other way around.

Administrator powers deserve extra care when two orgs are tied together.

The source org can create accounts in the target org. If the service account behind the API token is too powerful, anyone who controls the source org can effectively control the target org. This is a trust relationship in one direction, and it should be designed deliberately.

The best place to make mistakes is a place where mistakes are free.

Okta offers preview or sandbox orgs designed for experiments. Build a test pair that mirrors the real pair as closely as possible: similar usernames, similar groups, a few dozen representative people. Then run through every scenario in this post before touching production.

A careful rollout feels slow on day one and fast on day thirty.

A link between two orgs is also a link for attackers. Knowing the likely attacks tells you where to place the locks.

The “raise the drawbridge” plan

Write down, in advance, the steps to cut the connection quickly if either org is suspected to be compromised: disable provisioning in the source, revoke the token in the target, turn off the sign-in trust, and clear sessions in both orgs. A plan written during an emergency is rarely a good plan.

Signed notes need keys. Keys expire. Plan for it before it happens.

The signature on each sign-in note is made with a certificate: a digital document that holds a public key and has an end date. The target org keeps a copy of the source’s certificate so it can check signatures. When the certificate expires or is replaced, the target must learn about the new one. If it does not, every sign-in fails with a signature error, and people are suddenly locked out of the target.

Copying people from one place to another is also copying personal data. Laws and contracts care about that.

Many organizations keep separate orgs on purpose: for different countries, subsidiaries, or customers. Rules may limit what personal information can move between them, or where it can be stored. Before connecting, ask whether moving each attribute is allowed and needed.

Two systems talking over the internet will sometimes fail. Good design expects it.

Provisioning happens by sending requests across the internet. Networks drop, services restart, and Okta limits how fast any org may send or receive requests. A healthy connection copes with these things by retrying and by reporting what it could not do.

Planning for bad days

You cannot fix what you cannot see. A few simple measurements tell you whether the connection is healthy.

Both orgs write records of what happens: sign-ins, provisioning actions, errors, and administrative changes. Reading these on a schedule, or sending them to a central system, catches problems early.

Alerts worth having

• Any provisioning failure that repeats more than a few times.
• Any change to the connection’s mapping, token, or assignments.
• Any new administrator role in the target.
• Any sign-in error spike into the target.

A connection with no owner is a connection waiting to fail.

These shapes have helped many organizations.

These mistakes look sensible when made and cause trouble later.

A short list to carry into a design meeting.

Split every problem into two questions: is it about sign-in, or is it about copying people?

flowchart TD
  S["Problem reported"] --> Q1{"Can the person sign in to the target?"}
  Q1 -- No --> Q2{"Does the account exist in the target?"}
  Q2 -- No --> P1["Provisioning problem - check assignment, token, mapping, conflicts"]
  Q2 -- Yes --> Q3{"Is the error about the signature or trust?"}
  Q3 -- Yes --> T1["Check certificate, clock, and trust settings"]
  Q3 -- No --> T2["Check account status, session rules, and routing"]
  Q1 -- Yes --> Q4{"Are the details or groups wrong?"}
  Q4 -- Yes --> P2["Check mapping, source of truth, and recent edits in the target"]
  Q4 -- No --> Q5{"Is access to applications wrong?"}
  Q5 -- Yes --> P3["Check group membership and application assignments in the target"]
  Q5 -- No --> D["Review the logs for the time of the problem"]
    

Four stories show Org2Org at work.

A connection copies whatever it finds. If the data is messy, the mess is copied too.

Many Org2Org projects stall not because the connection is hard, but because the people lists on either side are untidy. Spelling differences, old accounts, shared mailboxes, and people who left long ago all show up as soon as two lists are compared. A short cleaning exercise before the first assignment is the cheapest insurance you can buy.

A simple cleaning routine

Org2Org is one tool among several. Knowing the alternatives helps you choose honestly.

Connecting two Okta orgs is not the only way to share people and trust. Depending on your size and goals, another approach may be simpler or stronger. The table compares common choices in plain terms.

A simple way to choose

Every connection should have a planned ending, even if the ending is years away.

Orgs get merged, businesses are sold, and projects finish. When that day comes, you need to turn off the connection without locking people out or leaving dangerous leftovers. Thinking about the ending early makes the middle simpler.

What to decide before disconnecting

• Will the people in the target keep their accounts, or be removed?
• If they keep them, who becomes the source of truth for them afterwards?
• How will they sign in once the source no longer vouches for them?
• What happens to groups that were pushed from the source?
• When will the API token and signing certificate be retired?

The technical part is only half the work. People need to know what is happening and who will help.

The help desk needs a short guide

When two orgs are connected, support questions change. “I cannot sign in” might mean the source, the target, the routing rule, or the person’s account state. Give the help desk a one-page guide that starts with the two big questions: did the person sign in to the source first, and does their account exist in the target.

Telling people what is happening

Explain in plain language what the connection does, what changes for them, and where to ask for help. Most people only need to know: “Sign in at the usual place and click this tile.” A short announcement, a one-page guide, and a way to report problems prevent most frustration.

Counting the cost

Connections can affect licensing and capacity. Extra accounts in the target may count toward costs. Large batches use rate limits that other work also needs. Ask your Okta contact how licensing treats copied users and review the numbers before widening the scope.

Every connection should fit on a single page that anyone on the team can read in five minutes.

When the original builder is on holiday, or has moved to another team, the next person should be able to understand the connection quickly. A one-page record makes that possible. It is not paperwork for its own sake; it is the thing that lets a worried administrator at two in the morning find the answer in seconds.

The launch is exciting. The years after the launch are where reliability is earned.

Once the connection is running, small regular habits keep it dependable. The table below groups them by how often they happen.

The same features that save work also create new things to look after.

A steady rhythm keeps the connection healthy year after year.

flowchart LR
  A["Design"] --> B["Build in preview pair"]
  B --> C["Roll out in waves"]
  C --> D["Watch"]
  D --> E["Reconcile monthly"]
  E --> F["Renew on schedule"]
  F --> G["Review twice a year"]
  G --> A
    

Three people, one connection, and a clear reason behind each outcome.

Meera, a new engineer in the regional office

Meera is hired by the regional company, which runs its own Okta org connected to the global hub. The global HR system creates her record, and the hub org creates her account and adds her to the “Regional Engineering” connection group. Within minutes, the regional org has a matching account with the right name, email, and department. On her first morning she opens the hub dashboard, clicks the regional tile, and lands signed in without typing another password. She joins the engineering group automatically and sees her team’s applications.

Arjun, a manager who moves departments

Arjun moves from engineering to product. HR updates his department. The hub org changes his profile and moves him between groups. The connection sends the new department and group membership to the regional org. He loses access to engineering tools and gains the product tools without anyone in the region doing anything. A week later, a regional administrator tries to fix his job title directly in the regional org. The next update from the hub changes it back, and the administrator learns that fixes must be made at the source.

Kavita, the administrator who looks after the connection

Kavita owns the connection. On the first of each month she runs a comparison between hub and region. It shows one person present in the region but not in the hub. She finds the account was created by hand during an emergency, removes it, and records the reason. Her calendar warns her that the signing certificate expires in ninety days. She creates the new certificate, loads it into the test pair, and schedules the switch for a quiet Thursday morning. She also checks that the token owner account is healthy and that two emergency administrators in the region can still sign in locally.

Quick reminders for the words used most often.

One org sends, one org trusts, and someone looks after the link.

Org2Org lets one Okta org send people and groups to another and vouch for them at sign-in. The source org holds the truth, the target org receives it, and a token and certificate hold the connection together. The best setups are small in scope, strict about who has power, careful about attributes, tested in a preview pair, rolled out in waves, and watched for expiries and failures. The worst setups give too much power to a token, let two orgs edit the same facts, or forget that keys expire.