SSO Object v5 | Alchemer REST API

The following API calls are currently available for the SSO (Single Sign-On) object:

GET LIST
GET SSO
CREATE SSO

UPDATE SSO
DELETE SSO

GET LIST - Get a list of all SSO integrations in your account.

https://api.alchemer.com/v5/sso

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.

Parameters	Example	Required
Authentication Credentials	api_token=abcd12345&api_token_secret=abcd12345	True
page	page=3	False
resultsperpage	resultsperpage=100	False

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.alchemer.com/adfs/services/trust",
      "login": "https://example.alchemer.com/adfs/ls/",
      "logout": "https://example.alchemer.com/adfs/ls/",
      "cert_fingerprint": "abcd1234efgh5678ijkl9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-06-22 17:23:43",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "0",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.example.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.example.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

GET SSO - Get information about a specific SSO integration in your account.

https://api.alchemer.com/v5/sso/[SSOID]

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.

Parameters	Example	Required
Authentication Credentials	api_token=abcd12345&api_token_secret=abcd12345	True

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.alchemer.com/adfs/services/trust",
      "login": "https://example.alchemer.com/adfs/ls/",
      "logout": "https://example.alchemer.com/adfs/ls/",
      "cert_fingerprint": "1234abcd5678efgh9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-06-22 17:23:43",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "0",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.example.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.example.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

CREATE SSO - Set up SSO in your account.

https://api.alchemer.com/v5/sso?_method=PUT&name=SurveyRespondentAuthentication&type=Account&entity_id=example&login=https://www.login.com&logout=https://www.logout.com&cert=-----BEGIN+CERTIFICATE-----%0D%0AMIagh%DCCBCCg-----END+CERTIFICATE-----

Parameters	Value/Example	Required
Authentication Credentials	api_token=abcd12345&api_token_secret=abcd12345	True
name	Internal Title (ex. Survey Respondent Authentication)	True
type	Authentication Type (Account, Survey)	True
status	Active, Closed	False
entity_id	This is the globally-unique URL/string of your IdP entity.	True
login	Login URL	True
logout	Logout URL	True
cert	This is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer.	True
attributes[attribute name]	Array of data attributes used with Survey Authentication Type (ex. attributes[Dept]=Sales)	False
metadataurl	Identify Provider Metadata URL (allow Alchemer to pull SAML settings from your IdP metadata	False
userdisable	0, 1, 2, etc. (Integer value indicating number of weeks of inactivity in Alchemer before user is disabled)	False
createusers	true, false (if set to true, users are automatically created in Alchemer)	False
userrole	Role ID	False
userteam	Team ID	False
userlicense	License ID*	False
usersolo	true, false	False
notificationemail	email address (emails will be sent here in the event of errors when creating new users)	False

*License IDs

License	ID
Reporting	19
Basic	3
Standard	14
HR Professional	6
Market Research	16
Educational	20
Full Access	7

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.alchemer.com/adfs/services/trust",
      "login": "https://example.alchemer.com/adfs/ls/",
      "logout": "https://example.alchemer.com/adfs/ls/",
      "cert_fingerprint": "1234abcd5678efgh9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-09-28 17:30:01",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "xxxxxx",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

UPDATE SSO - Update/Change SSO integration information.

https://api.alchemer.com/v5/sso/[SSOID]?_method=POST

Parameters	Value/Example	Required
Authentication Credentials	api_token=abcd12345&api_token_secret=abcd12345	True
name	Internal Title (ex. Survey Respondent Authentication)	True
type	Authentication Type (Account, Survey)	True
status	Active, Closed	False
entity_id	This is the globally-unique URL/string of your IdP entity.	True
login	Login URL	True
logout	Logout URL	True
cert	This is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer.	True
attributes[attribute name]	Array of data attributes used with Survey Authentication Type (ex. attributes[Dept]=Sales)	False
metadataurl	Identify Provider Metadata URL (allow Alchemer to pull SAML settings from your IdP metadata	False
userdisable	0, 1, 2, etc. (Integer value indicating number of weeks of inactivity in Alchemer before user is disabled)	False
createusers	true, false (if set to true, users are automatically created in Alchemer)	False
userrole	Role ID	False
userteam	Team ID	False
userlicense	License ID*	False
usersolo	true, false	False
notificationemail	email address (emails will be sent here in the event of errors when creating new users)	False

*License IDs

License	ID
Reporting	19
Basic	3
Standard	14
HR Professional	6
Market Research	16
Educational	20
Full Access	7

Response Example (.json format):

{
  "result_ok": true,
  "data": {
    "123": {
      "id": "123",
      "entity_id": "https://example.alchemer.com/adfs/services/trust",
      "login": "https://example.alchemer.com/adfs/ls/",
      "logout": "https://example.alchemer.com/adfs/ls/",
      "cert_fingerprint": "1234abcd5678efgh9101112",
      "customerid": "xxxxx",
      "created": "2017-02-06 15:51:04",
      "dModified": "2017-09-28 17:30:01",
      "status": "Active",
      "cert_domain": null,
      "user_last_modified": "xxxxxx",
      "creatusers": "false",
      "userteam": "0",
      "userlicense": "0",
      "userrole": "2",
      "iUserIDCreated": "xxxxx",
      "usersolo": "true",
      "email_notification": null,
      "disable_users": "0",
      "weeks_to_disable": null,
      "type": "Survey",
      "attributes": [
        "Dept",
        "Street",
        "DisplayName"
      ],
      "name": "Survey Respondent Authentication",
      "force_sso_login": "0",
      "user_deleted": null,
      "deleted": null,
      "sp_metadata": "app.sgizmo.com/login/getsamlxml/idp/1234abcd5678efgh9101112",
      "sp_login": "app.sgizmo.com/ssologin.php?idp=1234abcd5678efgh9101112"
    }
  }
}

DELETE SSO - Delete specific SSO integration from your account.

https://api.alchemer.com/v5/domain/[DomainID]?_method=DELETE

Parameters	Value/Example	Required
Authentication Credentials	api_token=abcd12345&api_token_secret=abcd12345	True

Response Example (.json format):

{
  "result_ok": true,
  "status": "success"
}

Glossary of SSO Terms

Active Directory Federated Services (AD FS)

Microsoft's IdP software.

Entity ID

This is the globally unique URL/string of your IdP entity. It's like a mailing address that we, the service provider, use to contact your IdP.

Your Entity ID can be found in your AD FS Management Console by right-clicking the AD FS Folder and selecting Edit Federation Service Properties.

The URL in the Federation Service identifier field.

Identity Provider (IdP)

The source of truth for usernames and passwords.

Login URL

This is the URL for logging in to your IdP. The Login URL is often very similar to the Entity ID URL. This is where we will send the SAML request.

Name ID

Unique string to identify users. When sending Name ID to Alchemer we recommend it be their email address.

Service Provider (SP)

The web-based application/s that are accessed via the IdP.

Security Assertion Markup Language (SAML)

an XML standard that allows secure web domains to exchange user authentication and authorization data. Using SAML, an online service provider can contact a separate online identity provider to authenticate users who are trying to access secure content.

Single Sign-On (SSO)

Provides partner companies with full control over the authorization and authentication of hosted user accounts that can access web-based applications.

SSL Certificate

This is your certificate file (.crt) for your IdP which can be downloaded from your SSL Issuer. NOTE: If the file you have also has the ‘intermediate’ or ‘root’ certificate chains in them, that’s fine, as long as it has the main certificate for the domain included.

User Principal Name (UPN)

The Name of the system user in email address format.