Course contents

Unit 3: Underlay, overlay and TLOCLesson 3.5 (5 of 7 in this unit)18 of 27 in the Cisco SD-WAN course

Organization name and certificate domain

Why the organization name must match on every controller and WAN Edge, how it relates to certificates and the Validator name, and how to find a mismatch.

Intermediate · 9 min read

You'll learn to explain what the organization name is used for, why it has to be identical across the fabric, and find a mismatch when a device fails to authenticate.

Technical definition

Organization name is a text value configured on every controller and WAN Edge in one SD-WAN fabric. It is carried in the device certificates, and devices compare it with their own when they set up a control connection, so only members of the same organisation connect to each other.

A router that has everything except the right name

BR-01 has a working internet link, a correct system IP and a valid certificate, yet it does not get a control connection to the Controller (formerly vSmart). The Manager (formerly vManage) lists the attempt as failed. When transport and DNS are fine, one of the first values to compare is the organization name, because a single different character is enough to stop authentication.

What the name does

A fabric needs a way to say which devices belong to it. Certificates prove that a device was issued an identity, and the organization name ties that identity to this particular network. The name appears in the certificate subject of controllers and WAN Edges, and each device is also configured with it. When two devices build a control connection, each side checks that the other side's name matches its own.

What the organisation name does
What the organisation name doesIt is checked on every control connection.MatchesConnection continuesMismatchConnection refusedor

On small screens, swipe sideways or focus the diagram and use the arrow keys.

A mismatch refuses the connection.
What the name does
What the name doesWhere the name is set or held; Purpose. Manager settings: The fabric-wide value that other devices are expected to match Each controller's configuration (Controller, Validator): Used when it checks incoming devices Each WAN Edge's configuration: Used when it checks the controllers it connects to The device certificate: Carries the name the peer compares againstWhere the name is set orheldPurposeManager settingsThe fabric-wide value that other devices are expected to matchEach controller'sconfiguration (Controller,Validator)Used when it checks incoming devicesEach WAN Edge'sconfigurationUsed when it checks the controllers it connects toThe device certificateCarries the name the peer compares against

On small screens, swipe sideways or focus the diagram and use the arrow keys.

Each item on the left, with what it means on the right.

Because the certificate carries the name, correcting the configuration alone does not necessarily fix a mismatch. If the name in the certificate is wrong, the certificate may have to be issued again after the name is corrected. How certificates are issued and installed is the subject of a later lesson on the certificate process.

Organisation name and the domain

The lesson title pairs the name with a certificate domain. These are two different things that are often configured together. The organization name is a label for the fabric. The domain or address used to reach the Validator is how a device finds the first controller. Both appear in the system configuration, and a fault in either gives a failed connection, with different clues.

Where the name appears
Where the name appearsIt is set in three places.ManagerAdministration settingsController and ValidatorSystem configurationWAN EdgeSystem section

On small screens, swipe sideways or focus the diagram and use the arrow keys.

They must match.
Organisation name and the domain
Organisation name and the domainFault; Typical sign. Wrong or unresolvable Validator name: The device does not reach the Validator at all Wrong organization name: The connection starts, then authentication is refused Wrong or expired certificate: Authentication is refused, and the reason points at the certificate Wrong clock on the device: The certificate looks not yet valid or expired when it is notFaultTypical signWrong or unresolvableValidator nameThe device does not reach the Validator at allWrong organization nameThe connection starts, then authentication is refusedWrong or expiredcertificateAuthentication is refused, and the reason points at the certificateWrong clock on the deviceThe certificate looks not yet valid or expired when it is not

On small screens, swipe sideways or focus the diagram and use the arrow keys.

Each item on the left, with what it means on the right.

Configuring and reading it

system system-ip 10.255.2.1 site-id 101 organization-name LAB-EXAMPLE sp-organization-name LAB-EXAMPLE vbond vbond.example.net

Fragment of an IOS XE SD-WAN configuration for BR-01, shortened. LAB-EXAMPLE and vbond.example.net are placeholders. The Validator can be given as a name or an address, and the exact keywords can differ by release, so check yours. Most networks push these settings from a Manager template or configuration group.

Example output written for this lesson, simplified; real output has more fields and a different layout
BR-01#show sdwan control local-properties
organization-name  LAB-EXAMPLE
system-ip          10.255.2.1
site-id            101
certificate-status Installed
...
The first line is the name this router will present and compare. It must match the Manager's value character for character. The lines marked with dots stand for fields left out here.
Example output written for this lesson, simplified; real output has more fields and a different layout
BR-01#show sdwan control connection-history
PEER TYPE  SYSTEM IP    STATE      LOCAL ERROR      REMOTE ERROR
vsmart     10.255.0.11  connect    ORGNAMEMISMATCH  NOERR
vsmart     10.255.0.11  tear_down  ORGNAMEMISMATCH  NOERR
A history of failed attempts with an error code is the quickest way to tell a name mismatch from a transport or certificate problem. The error text and its spelling vary by release, so treat this line as an illustration of the kind of message to look for and check the code list for your version.

Finding a mismatch

Finding a mismatch
Finding a mismatchCompare the name on each component.Edgeshow running-configControllersame commandCompareexact text

On small screens, swipe sideways or focus the diagram and use the arrow keys.

Look for spaces and case.
  1. Confirm that transport and DNS work first, using the transport-side checks, so a name fault is not confused with a network fault.
  2. Read the router's own values with show sdwan control local-properties.
  3. Read the connection history for an error that names the organisation or the certificate.
  4. Compare the router's value with the Manager's settings, character by character, including case and spaces.
  5. If the configured value is right but the error persists, check which name the certificate contains.
  6. Also check the router's clock, because a wrong time makes valid certificates look invalid.

Learn more: System IP, Site ID and Device IdentityLogical Overlay and Encrypted Tunnel ConstructionNAT Traversal, DNS and Firewall Dependencies

Mistakes with the organization name

  • Retyping the name by hand on each device. Copy it from one source, since case and spaces count.
  • Treating it as an internet domain. It is a label; it does not have to exist in DNS.
  • Fixing the router configuration while the certificate still carries the old name.
  • Blaming the certificate when the actual fault is the clock or the Validator name.

Test yourself on the organization name

Predict · scenario 1

BR-01 reaches the Validator, but the control connection to the Controller is refused with an organisation-name error. The internet link and DNS work. What is the most likely cause?

Predict · scenario 2

Which statement about the organization name is correct?

Predict · scenario 3

A router's configuration was corrected to the right organization name, but it is still refused. What should be checked next?

FAQ

Is the organization name a domain name?
No. It is a text label chosen for the fabric and does not need to resolve in DNS. It is separate from the DNS names or addresses used to find the Validator, although both must be right for a device to connect.
What happens if one router has a different spelling?
It fails to authenticate with the controllers, because the value in its configuration and certificate does not match what they expect. Capital letters, spaces and hyphens count, so copy the exact string rather than retyping it.
Can I change the organization name later?
It can be changed, but certificates and every device configuration depend on it, so it is a coordinated change, not a quick edit. Check your release's guide and plan the procedure before starting.