NetX SAML Services

NetX SAML SSO is a single sign-on authentication and trust system between NetX and a third-party SSO provider. SAML stands for Security Assertion Markup Language; NetX supports the SAML v2.0 specification. SAML allows NetX to provide a standardized mechanism for creating trust between the client's user authentication scheme and NetX.

Integrating NetX with a remote SSO system assumes the following:

  • That an SSO system is already deployed and functional; assisting with the setup of an SSO system is outside of the responsibility of NetX engineers.
  • That at least one other application has been successfully configured to use the existing SSO system; this ensures that issues with the integration are specific to NetX and not a general issue with the SSO deployment.

Supported vendors

The following are vendors that other customers have successfully integrated with in the past:

  • Microsoft Active Directory Federated System (ADFS)
  • Ping One
  • NetIQ
  • Shibboleth
  • Okta

Quick start guide

NetX's SAML integration is enabled by entering the correct values inside the samlServices.xml configuration file. At a minimum, NetX needs the following information in order to be configured with an external SAML 2.0 Identity Provider (IdP):

Item Description Related property
A map of SAML attributes to designate user profile values in NetX

At a minimum, you must define the following in NetX:

    1. login (username)
    2. email
    3. first name
    4. last name
<saml> and <netx> name/value pairs, respectively. See example samlServices.xml file below.
The URL of the Identity Provider This is where Users who are not already authenticated will be routed from NetX. Eg: https://adfs.netx.net/adfs/ls. In the SAML Services configuration file, this is value of the idpUrl property. idpURL
The X.509 certificate You must provide NetX with your public X.509 certificate that corresponds to the Identity Provider endpoint. This must be in the PEM format. This certificate file must be installed on the NetX server, and its path set in the certificateLocation property. See X.509Certificate for more details. certificateLocation
The user level  Users that are new to NetX, that authenticate through SAML Services, will be automatically set to a specific user level. The default is consumer. Please set the userLevel property to another value if you want a different default. After specific users login, their user level can be changed manually by an Administrator-level user. userLevel
 


samlServices.xml

All of the above information needs to be provided inside the main SAML configuration file, samlServices.xml. The file must be stored in the following locations:

Linux/Unix: <application root>/netx/config (e.g. /netx/<instance name>/netx/config)
Windows: <application root>\netx\config (e.g. C:\Program Files\NetXposure\netx\config)

In version 8.11+, a samlServices.xml with example values is deployed inside the above locations to assist with configuration.

Below is an example configuration:

<?xml version="1.0" encoding="UTF-8"?>
<samlServices>
    <samlService>
        <name>netx</name>
        <idpUrl>https://adfs.netx.net/adfs/ls</idpUrl>
        <certificateLocation>/netx/saml/netx/config/x509.cer</certificateLocation>
        <userLevel>consumer</userLevel>
        <attributes>
            <attribute>
                <saml>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname</saml>
                <netx>name1</netx>
            </attribute>
            <attribute>
                <saml>login</saml>
                <netx>login</netx>
            </attribute>
	    	<attribute>
                <saml>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname</saml>
                <netx>name3</netx>
            </attribute>
            <attribute>
                <saml>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</saml>
                <netx>email</netx>
            </attribute>
            <attribute>
                <saml>http://schemas.xmlsoap.org/claims/Group</saml>
                <netx>groups</netx>
            </attribute> 
        </attributes>
        <groups>
            <group>
                <saml>Domain Users</saml>
                <netx>SSO Group</netx>
            </group>
            <group autoAdd="true">
                <netx>Approval Required</netx>
            </group>
         </groups>
    </samlService>
</samlServices>


Please understand that various SAML implementations (and vendors) provide different SAML attribute names. In the example above, these are names usually provided by Microsoft ADFS, which provides the name with the complete URI for that attribute (eg "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"). In other cases, something more simple may be provided. by your IdP. Please consult with your IdP administrator for assistance with what your particular IdP will be sending in the SAML response.

Mapping attributes

In order for NetX to properly register incoming users from SAML, NetX needs to know something about that user. At the very least, NetX needs a first and last name, an email, and a login (though you can easily use an email as the login as well). In order to obtain this information, the SAML must provide this information in the AttributeStatement block of the response.  That might look like this snip of SAML:

    <saml:AttributeStatement>
      <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test@example.com</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="eduPersonAffiliation" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">users</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">examplerole1</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>

The remote IdP is adding user attributes to the SAML response so that applications like NetX can understand a little bit about the incoming user. In this example, we have the following metadata:

Field Value
uid test
mail test@example.com
eduPersonAffiliation users, examplerole1

Please note that in this case, the user attributes are contained inside of the "saml:AttributeStatement" block. This is common, but there is a property for designating a different (XML) block if your SAML is formatted differently. Next, the field name is designated by the "Name" attribute of the "saml:Attribute" nodes; and the value is designed in the child node: saml:AttributeValue. However, some SAML formatting adds a "FriendlyName" attribute to the "saml:Attribute" nodes; these are often more human readable. However, NetX will only search for "Name" attributes; so ensure your SAML mapping uses the values from that field.

For example, we've seen something like this from Shibboleth:

<saml2:AttributeStatement>
	<saml2:Attribute 
		FriendlyName="mail" 
		Name="urn:oid:0.9.2342.19200300.100.1.3"
		NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
		<saml2:AttributeValue 
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:type="xsd:string">test@example.com</saml2:AttributeValue>
	</saml2:Attribute>
	...
</saml2:AttributeStatement>

So in this case, you would map "urn:oid:0.9.2342.19200300.100.1.3" (and not "mail") to the NetX email field. Like this:

<attribute>
    <saml>urn:oid:0.9.2342.19200300.100.1.3</saml>
    <netx>email</netx>
</attribute> 

 

If you are unsure, please capture a SAML response and update your configurations to match your SAML response. If there is not sufficient user attributes in your SAML response (perhaps the email is missing), please consult with your IdP administrator so that all required user attributes are provided.

Mapping groups

NetX's SAML integration provides the ability for groups to be mapped from your SSO provider to NetX's internal groups system. This can be accomplished by following the steps below:

  1. In the samlServices.xml file, define the inbound SAML attribute with the correct value from your provider. Map this to the "groups" netx attribute. For example:

    	<attribute>
    		<saml>http://schemas.xmlsoap.org/claims/Group</saml>
    		<netx>groups</netx>
    	</attribute>  
  2. Then, map your provider's group names to their destination groups in NetX. In the example below, the ADFS group "Domain Users" will be mapped over to the NetX group "SSO Group".

     <groups>
    	 <group>
         	<saml>Domain Users</saml>
            <netx>SSO Group</netx>
         </group>
     </groups>

However, you can also configure your SAML Service to simply add all users to a specific group. That was illustrated in the example above; like this:

            <group autoAdd="true">
                <netx>Approval Required</netx>
            </group>

For this, you can omit the "saml" designation, as there is no mapping in this scenario. To active the auto-add function, you must add the "autoAdd" attribute to the "group" node.

However, there are some legacy Directory Server (LDAP) properties that can affect this behavior, specifically these:

user.directory_auto_create_groups
user.directory_auto_add_to_group

 

"user.directory_auto_create_groups" defaults to "true", but if it's set to "false", then these <netx> groups will NOT be auto-created (and would then need to be created manually).

"user.directory_auto_add_to_group" will work regardless (and perhaps redundantly) to this new feature. Please be aware that this property is global and affects all LDAP and/or SAML configurations.

SaaS implementation

 If you have a NetX SaaS deployment, you will need to fill out a SAML Worksheet and submit it to your Onboarding Specialist or Support so that the above information can be captured and configured in your environment. Professional Services charges may be applicable if advanced assistance is needed to help configure the integration.

Technical reference guide

NetX SAML Services

The basic concepts are:

  • A single NetX endpoint for all services: "/saml/*"
  • Each SAML service is defined in the samlServices.xml configuration file.
  • Each named service is then attached to that SAML endpoint. For example, if you have a named "acme" service, then that service is accessible at: "/saml/acme".
  • GETs are for obtaining a SAML request, and SAML responses are POSTed to the same endpoint.

SSO Workflow

The following flowchart diagrams the flow of information and the routing of the user's session through the SAML-based SSO process. The yellow boxes represent actual NetX URL endpoints. The purple and gray boxes show NetX properties (in purple, and example values in gray). Decisions are shown in green diamonds. The remote identity provider (IdP) is shown in purple; this is your remote SSO system/federation. And finally, if all work as expected, the user is either logged-in, or denied for any failure in the process.

SamlServices.xml

Here's an example configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<samlServices>
    <samlService>
        <name>netx</name>
        <idpUrl>https://adfs.netx.net/adfs/ls</idpUrl>
        <certificateLocation>/netx/saml/netx/config/x509.cer</certificateLocation>
        <userLevel>consumer</userLevel>
        <attributes>
            <attribute>
                <saml>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname</saml>
                <netx>name1</netx>
            </attribute>
            <attribute>
                <saml>login</saml>
                <netx>login</netx>
            </attribute>
	    	<attribute>
                <saml>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname</saml>
                <netx>name3</netx>
            </attribute>
            <attribute>
                <saml>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</saml>
                <netx>email</netx>
            </attribute>
            <attribute>
                <saml>http://schemas.xmlsoap.org/claims/Group</saml>
                <netx>groups</netx>
            </attribute> 
        </attributes>
        <groups>
            <group>
                <saml>Domain Users</saml>
                <netx>SSO Group</netx>
            </group>
         </groups>
    </samlService>
</samlServices>

SAML services configuration properties

Property Description
postAuthUrl

After the user is fully authenticated with NetX (and SAML), where should they be directed too? The default is /app, but this could also be a Portal.

Type: URL

Example: /portals/myPortal

certificateLocation

Required: Path to the X509 certification file (public key). The certificate is loaded once; so if you change it, then you must restart the NetX instance.

Type: String

Example: /netx/acme/netx/config/x509.cer

base64

Whether the SAML will be base64 encoded (it should be). Warning: Only set to "false" if you know what you're doing.

Type: Boolean

Example: true / false

samlRequestParameter

When a SAML Response is received via HTTP POST, this is the named parameter which the service will find the SAML body. Warning: Only set this if you know what you're doing.

Type: Boolean

Example: true / false

certificateTagName

When a SAML Response is received via HTTP POST, this is the named SAML/XMP node for the embedded certificate. Warning: Only set this if you know what you're doing.

Type: String

Example: ds:X509Certificate

certificateConditionsTagName

When a SAML Response is received via HTTP POST, this is the named SAML/XMP node for the certificate conditions tag. Warning: Only set this if you know what you're doing.

Type: String

Example: saml2:Conditions

attributeStatementTagName

By default, NetX will attempt to find <saml2:AttributeStatement>, then <AttributeStatement>, then <saml:AttributeStatement>. If your SAML response uses some other convention, you can specify that here.

Type: String

Example: customNS:AttributeStatement

issuer

Where the remote IdP should redirect back to (POST). This is set to a default. Warning: Only set this if you know what you're doing.

Type: URL

Example: https://acme.netx.net/saml/acme

userLevel

By default, SAML users are created as consumer (2) level users. Furthermore, you can override this default by setting the user.sessionAutoRegisterLevel property to one of the integer equivalents. However, you can set the default user level per service with this parameter. Additionally, this parameter accepts either the integer equivalents, or the label-based Strings: browser, consumer, importer, producer, manager, directory, or administrator.

Type: String or int

Example: producer

groupRequired

By default, any IdP authenticated user will enter NetX at the specified userLevel; however, you may want to filter out users that have no mapped roles/groups. Setting this property to "true" will block access to users that have no mapped roles/groups. In this case, the user is routed to the noAccessUrl value.

Type: Boolean

noAccessUrl

If "groupRequired" is set to true, and the user is blocked access to NetX, then this is the URL where the user will be redirected after logging into the remote IdP. The default is present the NetX login screen (routed secondarily from /app).

Type: String

attributes

Attributes allows you to map incoming SAML attributes to NetX User attributes.

Type: Array

attribute

Each attribute map is contained within an attribute object, which consists of a saml (incoming) value, and a netx (outgoing) value. Basically: this equals that.

Type: Object

attribute/saml

SAML attribute to map to a NetX field. These fields can be either designed with saml:Attribute, saml2:Attribute or Attribute. The name is designed int he SAML as "Name". Values can be either designed with saml:AttributeValue, saml2:saml:AttributeValue or saml:AttributeValue.

Type: String

attribute/netx

NetX field to store the SAML value.

Type: String

groups

This block allow you to map a specially designated SAML attribute to a NetX group (placing the user in that Group). First, above in the attributes, you would map an inbound SAML attribute to groups. Each AttributeValue will be mapped using this groups block.

Type: Array

group

Type: Object

group/saml

 The SAML attribute value to match.

Type: String

group/netx

Then a match is found, into which group is the user made a member?

Type: String

group autoAdd

Adds all users to a specific group (see Mapping groups).

Type: Boolean

advertise

If set to true, the SAML Service will be displayed in the login UI for users to select when logging in.

Type: Boolean

description

Used to display a description of the SAML service to an end user in the login UI if the *advertise* boolean is set to true (see above). Note: this is no longer supported as of NetX 9.0.

Type: String

label

Used to display a label of the SAML service to an end user in the login UI if the advertise boolean is set to true (see above).

Type: String

samlService

Required: All SAML services properties are contained within this object.

Type: Object

name

Required: The name of the service (to be filled in by the configuring engineer, not the customer)

Type: String

Example: acme

idpUrl

Required: The URL to the remote Identity Provider (IdP)

Type: URL

NetX user attributes (for mapping):

  • login
  • name1 (firstname)
  • name2
  • name3 (lastname)
  • name4
  • email
  • phone1
  • phone2
  • phone3
  • phone4
  • organization
  • address1
  • address2
  • city
  • state
  • zip
  • country

X.509 Certificate

In order to properly utilize you SAML Service endpoint, each configuration requires that you provide a server-side path to the corresponding X.509 certificate. You must obtain this certificate from your IdP system directly; and it must be installed on the NetX server in order to establish trust. Only SAML responses to each endpoint that can be validated with the specified certificate will be accepted. 

NetX requires that the X.509 certificate be formatted as PEM. PEM files are X.509v3 files which contain ASCII (Base64) armored data prefixed with a "—– BEGIN …"  line. If you have DER, or other certificate format, you must first convert that to PEM. It is also possible to set up the service with a bogus PEM certificate (so the service can initialize itself), test the SAML endpoint, and in the resulting error (in your browser), the raw SAML will be printed. Inside that SAML, you can find the embedded X.509 certificate. For example:

            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>MIIC3DDDAcSgAwIBAgIQWgvEwjIZ45pGh+L3Y3Pt6jANBgkqhkiG9w0BAQsFADAqMSgwJgYDVQQDEx9BREZTIFNpZ25pbmcgLSBhZGZzcG9jLm5ldHgubmV0MB4XDTE2MTIyOTAwNDkzM1oXDTE3MTIyOTAwNDkzM1owKjEoMCYGA1UEAxMfQURGUyBTaWduaW5nIC0gYWRmc3BvYy5uZXR4Lm5ldDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANLtcUvtqbpT395qYjUqQmaVIULco6pPGggG+9qO/Ag1SWmlxEDJfd8GFxPg5FWVp+VGH8xYyopjOJkcQjsKDN6cmGnv+pBbQ8D6xH0Dsw0IwL++lqVKHodIdbMZ2k48iBr22up+SedknHFv2IsBSOHuhgAr7WWCGiww1ZrbIMHRNOiPBp/ng5JqrlY6BlZz3dvSMo/rmWp2HTNwf3pIo0ELXI/pmURt5Yy/Z2U7Dd9XdffWJ+z7cozAC0hJTNW8ey1iArMJ0bCCnu1G3SdK65fiFh0YP1w/Iznr+GmUj57HKFCoSwge69Jy+4AJ07zmXGlpWOy6wZF/zEp8WerBrpkCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAxPzakPkj16aCCZkOFLw6+vaTOqYv3+KuJ64awrRGC6kQulysWzfdRGrkuXI+KulZgej9IkC4/ggmnjcBw49U4j3ViM1opJjyMNYwlmEcgOGYW6W3S+F45guyDk/wtCoKe1UgnTJKQBLkDO+c7G7qcN94GPN0/GnFEfSiIcV5Am+m3Z/faGGjAmHPq44JJPfnH7GU/tQiLoJenvUUkIXJPLsCXG1OngYSB9QJt1gBcw2PRLlFjEOTAtH4ZcKRybxBU7sg3jEHvhTTjKNdgB22BHxGs9lu4s3PoGb4+XinowwhLpoWl/lGVgBOAsx6zY/miqCzASKekOtgirX4HNaS+Q==</ds:X509Certificate>
                </ds:X509Data>
            </KeyInfo>

You can extract the certificate from that block and manually format it into a PEM file, like this:

-----BEGIN CERTIFICATE-----
MIIC3DDDAcSgAwIBAgIQWgvEwjIZ45pGh+L3Y3Pt6jANBgkqhkiG9w0BAQsFADAq
MSgwJgYDVQQDEx9BREZTIFNpZ25pbmcgLSBhZGZzcG9jLm5ldHgubmV0MB4XDTE2
MTIyOTAwNDkzM1oXDTE3MTIyOTAwNDkzM1owKjEoMCYGA1UEAxMfQURGUyBTaWdu
aW5nIC0gYWRmc3BvYy5uZXR4Lm5ldDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBANLtcUvtqbpT395qYjUqQmaVIULco6pPGggG+9qO/Ag1SWmlxEDJfd8G
FxPg5FWVp+VGH8xYyopjOJkcQjsKDN6cmGnv+pBbQ8D6xH0Dsw0IwL++lqVKHodI
dbMZ2k48iBr22up+SedknHFv2IsBSOHuhgAr7WWCGiww1ZrbIMHRNOiPBp/ng5Jq
rlY6BlZz3dvSMo/rmWp2HTNwf3pIo0ELXI/pmURt5Yy/Z2U7Dd9XdffWJ+z7cozA
C0hJTNW8ey1iArMJ0bCCnu1G3SdK65fiFh0YP1w/Iznr+GmUj57HKFCoSwge69Jy
+4AJ07zmXGlpWOy6wZF/zEp8WerBrpkCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEA
xPzakPkj16aCCZkOFLw6+vaTOqYv3+KuJ64awrRGC6kQulysWzfdRGrkuXI+KulZ
gej9IkC4/ggmnjcBw49U4j3ViM1opJjyMNYwlmEcgOGYW6W3S+F45guyDk/wtCoK
e1UgnTJKQBLkDO+c7G7qcN94GPN0/GnFEfSiIcV5Am+m3Z/faGGjAmHPq44JJPfn
H7GU/tQiLoJenvUUkIXJPLsCXG1OngYSB9QJt1gBcw2PRLlFjEOTAtH4ZcKRybxB
U7sg3jEHvhTTjKNdgB22BHxGs9lu4s3PoGb4+XinowwhLpoWl/lGVgBOAsx6zY/m
iqCzASKekOtgirX4HNaS+Q==
-----END CERTIFICATE-----

Such files can have "cer" or "pem" extensions (the extension is irrelevant).

Warning: please do NOT provide an encryption certificate (one that contains your private key for your IdP); instead, only ever provide the signing certificate (one that only contains the public key for your IdP).

SAML errors

The SAML Service system will present errors directly into the HTTP response. So if you are testing manually, you can determine various issues directly within the Web Browser. However, these messages also appear in the logs.

Error Reason
Assertion falls outside of valid conditions (NotBefore/NotOnOrAfter) The time embedded in the SAML falls outside of the acceptable bounds. That is, the SAML response has "not before" and "not on or after" conditions. If NetX finds the time is outside of these boundaries, this error will be thrown.
There are no nodes for ({attributeTagName}) No data (at all) could be obtained from the SAML response. Please check the SAML response and ensure that it contains the attribute, that there is an Attribute Statement block, and/or that the attributeStatementTagName corresponds to what is found in the SAML response.
There are no attributes for ({attributeTagName}) No attributes could be obtained from the SAML response, though some attribute nodes were found.. Please check the SAML response and ensure that it contains the attribute, that there is an Attribute Statement block, and/or that the attributeStatementTagName corresponds to what is found in the SAML response.
Failed to create user via mapping class Something went wrong when trying to create a NetX user with the available SAML data.
Failed to create user via mapping class Something went wrong when trying to create a NetX user with the available SAML data.
Exception Something unknown occurred; the exception message will be included.
No SAML No SAML body was received. Either the POST was blank, or the body was provided in a parameter other than "SAMLResponse".
General failure to obtain or parse SAML Some unknown error occurred while parsing the SAML; however, the exception message will be included.
Failed to trust SAML (signature/cert) An exception was thrown when trying to verify the signed SAML assertion using the provided X509 certificate. Either the certificate is not valid, the assertion was not signed, or it was signed incorrectly.

In the case of a simple error, NetX will present the user with the message within the standard error presentation:

However, in the case of an actual Exception, then the message will be presented in plain text, following by a raw dump of the SAML Response:

More complex samlServices.xml example

<?xml version="1.0" encoding="UTF-8"?>
<samlServices>
	<samlService>
		<name>my name 1</name>
		<idpUrl>my url</idpUrl>
		<postAuthUrl>my url</postAuthUrl>
		<certificateLocation>my certificate</certificateLocation>
		<base64>true</base64>
		<samlRequestParameter>SamlRequest</samlRequestParameter>
		<certificateTagName>certificateTagName</certificateTagName>
		<certificateConditionsTagName>certificateConditionsTagName</certificateConditionsTagName>
		<attributeStatementTagName>attributeStatementTagName</attributeStatementTagName>
		<issuer>my issuer</issuer>
		<userLevel>consumer</userLevel>
		<attributes>
			<attribute>
				<saml>http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname</saml>
				<netx>login</netx>
			</attribute>
			<attribute>
				<saml>http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname</saml>
				<netx>username</netx>
			</attribute>
		</attributes>
		<groups>
			<group>
				<saml>My role 1</saml>
				<netx>My group 2</netx>
			</group>
			<group>
				<saml>My role 1</saml>
				<netx>My group 2</netx>
			</group>
		</groups>
	</samlService>
	<samlService>
		<name>my name 2</name>
		<idpUrl>my url</idpUrl>
		<postAuthUrl>my url</postAuthUrl>
		<certificateLocation>my certificate</certificateLocation>
		<samlRequestParameter>SamlRequest</samlRequestParameter>
		<certificateTagName>certificateTagName</certificateTagName>
		<certificateConditionsTagName>certificateConditionsTagName</certificateConditionsTagName>
		<attributeStatementTagName>attributeStatementTagName</attributeStatementTagName>
		<issuer>my issuer</issuer>
		<userLevel>administrator</userLevel>
		<attributes>
			<attribute>
				<saml>http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname</saml>
				<netx>login</netx>
			</attribute>
		</attributes>
		<groups>
			<group>
				<saml>My role 1</saml>
				<netx>My group 2</netx>
			</group>
			<group>
				<saml>My role 1</saml>
				<netx>My group 2</netx>
			</group>
		</groups>
	</samlService>
</samlServices>

 

Example SAML response (for reference)

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6" Version="2.0" IssueInstant="2014-07-17T01:01:48Z" Destination="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685">
  <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="pfx2c5d7bde-e34e-f7d6-681e-e449f5a7f9b6" Version="2.0" IssueInstant="2014-07-17T01:01:48Z">
    <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
  <ds:Reference URI="#pfx2c5d7bde-e34e-f7d6-681e-e449f5a7f9b6"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><ds:DigestValue>/uzflv9Nplc1S32rm+NNLptmZ5g=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>DRBUFyw8K1gPnuw0LVoZGE3Ip5Ix4CR/UMXSO2lnBn3YIRi0RYVRdzwNMZiEcfGo/3sLkK3+tc+WjjIVhWZCjVXFSFMDyVm8MQwmDUXRatY5JW8+hJ+r1paZBDdxpLwr9dlmf5Wtc7zZlt9WlFeqiNKyejdj2fZm50NPInfdDeU=</ds:SignatureValue>
<ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0DAWBSMQswCQYDVQQGEwJ1czETMBEGA1UECAwKQ2FsaWZvcm5pYTEVMBMGA1UECgwMT25lbG9naW4gSW5jMRcwFQYDVQQDDA5zcC5leGFtcGxlLmNvbTAeFw0xNDA3MTcxNDEyNTZaFw0xNTA3MTcxNDEyNTZaMFIxCzAJBgNVBAYTAnVzMRMwEQYDVQQIDApDYWxpZm9ybmlhMRUwEwYDVQQKDAxPbmVsb2dpbiBJbmMxFzAVBgNVBAMMDnNwLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDZx+ON4IUoIWxgukTb1tOiX3bMYzYQiwWPUNMp+Fq82xoNogso2bykZG0yiJm5o8zv/sd6pGouayMgkx/2FSOdc36T0jGbCHuRSbtia0PEzNIRtmViMrt3AeoWBidRXmZsxCNLwgIV6dn2WpuE5Az0bHgpZnQxTKFek0BMKU/d8wIDAQABo1AwTjAdBgNVHQ4EFgQUGHxYqZYyX7cTxKVODVgZwSTdCnwwHwYDVR0jBBgwFoAUGHxYqZYyX7cTxKVODVgZwSTdCnwwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQ0FAAOBgQByFOl+hMFICbd3DJfnp2Rgd/dqttsZG/tyhILWvErbio/DEe98mXpowhTkC04ENprOyXi7ZbUqiicF89uAGyt1oqgTUCD1VsLahqIcmrzgumNyTwLGWo17WDAa1/usDhetWAMhgzF/Cnf5ek0nK00m0YZGyc4LzgD0CROMASTWNg==</ds:X509Certificate></ds:X509Data></ds:KeyInfo></ds:Signature>
    <saml:Subject>
      <saml:NameID SPNameQualifier="http://sp.example.com/demo1/metadata.php" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">_ce3d2948b4cf20146dee0a0b3dd6f69b6cf86f62d7</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData NotOnOrAfter="2024-01-18T06:21:48Z" Recipient="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685"/>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotBefore="2014-07-17T01:01:18Z" NotOnOrAfter="2024-01-18T06:21:48Z">
      <saml:AudienceRestriction>
        <saml:Audience>http://sp.example.com/demo1/metadata.php</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement AuthnInstant="2014-07-17T01:01:48Z" SessionNotOnOrAfter="2024-07-17T09:01:48Z" SessionIndex="_be9967abd904ddcae3c0eb4189adbe3f71e327cf93">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test@example.com</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="eduPersonAffiliation" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">users</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">examplerole1</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Frequently asked questions

How do I control what the usernames of my users will be?

In the SAML Services configuration file, you can map the username you want from your SAML IdP to the "login" field in NetX (in this context, "login" and "username" refer to the same thing). Like this:

<?xml version="1.0" encoding="UTF-8"?>
<samlServices>
    <samlService>
        ...
        <attributes>
            <attribute>
                <saml>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</saml>
                <netx>login</netx>
            </attribute>
...

In this example, the incoming "emailAddress" value providing by your SAML IdP is used for the NetX "login" (or username). 

It is important to understand that NetX can only obtain values for fields sent by your IdP. You may need to configure your IdP to provide more fields if you intend to use them within NetX.

What happens if I create an internal NetX account, and then later via a SAML Services configuration, that same login authenticates via SAML?

In this case, the original internal NetX account will be updated to reflect that this account is now associated with a remote SAML IdP. That is, this will now reflect that the account is controlled remotely (via SAML).

The original NetX password may be overwritten, and if configured, other aspects of the account may be changed automatically by the SAML configuration (groups, user fields, etc). Because user-level is determined at the time that accounts are created, past user levels from the original internal NetX account settings will generally be retained.

Was this article helpful?
0 out of 0 found this helpful