{"id":22343,"date":"2024-02-15T14:48:40","date_gmt":"2024-02-15T22:48:40","guid":{"rendered":"https:\/\/docs.extraview.com\/v22\/book\/saml-authentication\/"},"modified":"2024-02-15T16:32:15","modified_gmt":"2024-02-16T00:32:15","slug":"saml-authentication","status":"publish","type":"page","link":"https:\/\/docs.extraview.com\/v22\/saml-authentication\/","title":{"rendered":"SAML Authentication"},"content":{"rendered":"<p>Security Assertion Markup Language (SAML) is an open standard that allows an identity provider (IDP) to pass authorization credentials to a service provider (SP). SAML is the link between the authentication of users&#8217; identities and the authorization to use a service from the provider.&nbsp; ExtraView relies on the use of a third party IDP.<\/p>\n<p>SAML is used in conjunction with SSO and often with LDAP.&nbsp; With an operational ExtraView installation, the configuration of SAML requires these three steps:<\/p>\n<ol style=\"list-style-type:lower-alpha;\">\n<li>\n\t\tThe configuration of a working SSO external to ExtraView, in the ExtraView behavior settings and Configuration.properties file<\/li>\n<li>\n\t\tThe configuration of the third party Identity Provider (IDP)<\/li>\n<li>\n\t\tThe configuration of ExtraView SAML behavior settings and the storage of the certificate used by the IDP<\/li>\n<\/ol>\n<h3>\n\tLDAP Configuration<\/h3>\n<p>See the previous pages on <a href=\"\/external-authentication-ldap-sso-and-saml\/\">External Authentication &#8211; LDAP, SSO and SAML<\/a>.<\/p>\n<h3>\n\tSSO Configuration<\/h3>\n<p>See the previous page on <a href=\"\/ldap-connections-sso\/\">LDAP Connections with SSO<\/a>.<\/p>\n<h3>\n\tIdentity Provider (IDP) Configuration<\/h3>\n<p>The components of the IDP configuration depend on the provider itself, but it is expected that the most relevant points are:<\/p>\n<ul>\n<li>\n\t\tThe specification of the URL to which authentication responses are directed<\/li>\n<li>\n\t\tThe assertion key-value mapping for SSO keys; the SSO_PRIMARY_KEY must have an assertion in the authentication message to identify the ExtraView user.<\/li>\n<\/ul>\n<h3>\n\tExtraView Configuration<\/h3>\n<p>The following behavior settings should be configured as appropriate for your installation.&nbsp; You should determine the parameter values for all the settings below to be used in the authentication response before starting the configuration.<\/p>\n<table border=\"0\" cellpadding=\"2\" cellspacing=\"2\">\n<tbody>\n<tr bgcolor=\"#ddd\">\n<td>\n\t\t\t\t<strong>ExtraView Setting<\/strong><\/td>\n<td>\n\t\t\t\t<strong>Explanation<\/strong><\/td>\n<\/tr>\n<tr>\n<td>\n\t\t\t\tSSO_STATE<\/td>\n<td>\n\t\t\t\tThis behavior setting must be set to SAML<\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSAML_ASSERTION_CONSUMER_URL<\/td>\n<td>\n\t\t\t\tThis behavior setting is the URL of the consumer service that receives the authentication response from the SAML IDP. This is the URL that invokes the Consumer Servlet when the behavior setting <code>SSO_STATE<\/code> has a value of <code>SAML<\/code>.&nbsp; Typically this will have a value that looks similar to <code>https:\/\/myserver.mydomain.com\/Consumer<\/code>.&nbsp; This is the application URL registered with the IDP.<\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSAML_SSO_SERVICE<\/td>\n<td>\n\t\t\t\tThis behavior setting provides the URL of the SSO service to which the SAML SP sends an authentication request. This URL points to a target in the IDP<\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSAML_SSO_SP_ENTITY_ID<\/td>\n<td>\n\t\t\t\tThe SP Entity ID behavior setting is a URL or other identifier given by the Service Provider (SP) that uniquely identifies it to the IDP.&nbsp; This is derived from the metadata for the SP.&nbsp; A typical value is an XML fragment and will look similar to:<\/p>\n<p>\t\t\t\t<code>&lt;md:entitydescriptor entityid=<br \/>\n\t\t\t\t&nbsp; &nbsp; \"http:\/\/www.okta.com\/exki3aihaifAHCbex0h7\"<br \/>\n\t\t\t\t&nbsp; &nbsp; xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\"&gt;<br \/>\n\t\t\t\t&lt;\/md:entitydescriptor&gt;<\/code><\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSSO_DO_UPSERT<\/td>\n<td>\n\t\t\t\tThis is set within the Configuration.properties file if it the values from the authentication are to be updated within the ExtraView database with each authentication<\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSSO_PRIMARYKEY<\/td>\n<td>\n\t\t\t\tThis is the mapping for the user name that is set within the Configuration.properties file.&nbsp; This parameter must include the expected ExtraView User ID<\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSSO_SURNAME<\/td>\n<td>\n\t\t\t\tThis is the mapping for the user&#8217;s last name that is set within the Configuration.properties file<\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSSO_GIVENNAME<\/td>\n<td>\n\t\t\t\tThis is the mapping for the user&#8217;s given name that is set within the Configuration.properties file<\/td>\n<\/tr>\n<tr>\n<td valign=\"top\">\n\t\t\t\tSSO_EMAIL<\/td>\n<td>\n\t\t\t\tThis is the mapping for the user&#8217;s email address <span style=\"display: inline !important; float: none; background-color: transparent; color: rgb(51, 51, 51); font-family: Arial,Verdana,Helvetica,sans-serif; font-size: 12px; font-style: normal; font-variant: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-decoration: none; text-indent: 0px; text-transform: none; -webkit-text-stroke-width: 0px; white-space: normal; word-spacing: 0px;\">that is set within the Configuration.properties file<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>The IDP will typically require a valid security certificate to validate the encrypted signature in the authentication response from the IDP.&nbsp; This certificate is stored securely within ExtraView within the <a href=\"\/encryption-key-management\/\" style=\"color: rgb(51, 51, 51); text-decoration: none;\">Key Manager<\/a> administation utility.&nbsp; This is located at Admin &#8211;&gt; Advanced &#8211;&gt; <a href=\"\/encryption-key-management\/\">Encryption Key Management<\/a> &nbsp; The format for the certificate is known as PEM (Privacy Enhanced Mail).&nbsp; The name is somewhat of a misnomer as the certificates for SAML have no connection with email.&nbsp; The format is a Base 64 encoded striing of characters which is pasted into the&nbsp;<strong>Enter certificate PEM<\/strong> field within the Encryption Key Manager.&nbsp; If there is no entry in this field, the new entry you create for the key is added as a secret key only and is not used for SAML authentication.<\/p>\n<p>The entry in the key manager should look like this:<\/p>\n<ul>\n<li>\n\t\tName for the key &#8211; this must be <strong>SPKey<\/strong><\/li>\n<li>\n\t\tKey password &#8211; this must be <strong>password<\/strong><\/li>\n<li>\n\t\tCertificate PEM &#8211; this is the field where you paste the contents of the certificate<\/li>\n<\/ul>\n<p>The action to save a certificate in this field builds the appropriate credentials for the SAML certificate.<\/p>\n<h3>\n\tSAML Logging Configuration<\/h3>\n<p>When first establishing a connection to an IDP to perform SAML authentication it can be useful to add additional logging to view the precise details of the transactions.&nbsp; This configuration is achieved within the ExtraView <code><nobr>WEB-INF\/configuration\/Configuration.properties<\/nobr><\/code> file.<\/p>\n<div>\n\tAny property name within the Configuration.properties file that begins with <code>LOGBACK<\/code> is treated as a replaceable variable for the <code>logback.template <\/code>file.&nbsp; The&nbsp;<code>logback.template&nbsp;<\/code>file is part of the third-party SAML installation.<\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tThe replaceable variable modifies the <code>logback.template <\/code>file that creates the <code>logback.xml<\/code> configuration file that is then passed to the loggers for SAML.<\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tFor example, <code>LOGBACK_FILE_PATH_NAME_ABSOLUTE <\/code>is a replaceable variable that may have the value <code>\/tmp\/logs<\/code>.<\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tThe <code>Configuration.properties <\/code>file will contain the line:<\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\t<code>LOGBACK_FILE_PATH_NAME_ABSOLUTE=\/tmp\/logs<\/code><\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tThe <code>logback.xml <\/code>will contain the line:<\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\t<code>&lt;file&gt;__LOGBACK_FILE_PATH_NAME_ABSOLUTE__\/SAML.log&lt;\/file&gt;<\/code><\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tThis will result in a log file named <code>\/tmp\/logs\/SAML.log<\/code>.<\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tThere are two configurable files:<\/div>\n<ol>\n<li>\n\t\t<code>Configuration.properties<\/code>, which defines the <code>LOGBACK...<\/code> properties<\/li>\n<li>\n\t\t<code>logback.template<\/code>, which has replaceable variables surrounded by &#8220;__&#8221;.<\/li>\n<\/ol>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tThe following are the replaceable variables and the values specified in the delivered <code>Configuration.properties<\/code>:<\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\t<code>LOGBACK_FILE_PATH_NAME_ABSOLUTE=<\/code><\/div>\n<div>\n\t<code>LOGBACK_MAX_FILE_SIZE=10mb<\/code><\/div>\n<div>\n\t<code>LOGBACK_LOG_LEVEL=INFO<\/code><\/div>\n<div>\n\t&nbsp;<\/div>\n<div>\n\tThe value of the <code>LOGBACK_LOG_LEVEL<\/code> attribute may be one of the case-insensitive string values <code>TRACE<\/code>, <code>DEBUG<\/code>, <code>INFO<\/code>, <code>WARN<\/code>, <code>ERROR<\/code>, <code>ALL <\/code>or <code>OFF<\/code>.<\/div>\n<h3>\n\tBypassing SAML Authentication<\/h3>\n<p>There are some circumstances where you might want to bypass the SAML authentication, for example if the IDP service is not operable, or you need to access the ExtraView ADMIN account directly.&nbsp; To achieve this, include the parameter EV_BYPASS_SSO=YES on the URL, following the ExtraView address.&nbsp; This will produce the standard built-in ExtraView login screen for authorization.&nbsp; For example, your address might look like:<\/p>\n<p><code>http:\/\/myserver.mycompany.com\/evj\/ExtraView?EV_BYPASS_SSO=YES<\/code><\/p>\n<h3>\n\tSAML Authentication Via the CLI<\/h3>\n<p>CLI calls, by their very nature, cannot support SAML authentication, so the EV_BYPASS_SSO option is used to overcome this limitation.&nbsp; A&nbsp;<code>-B true<\/code> option on the CLI command line allows the user to enter a valid user ID and password for authentication.<\/p>\n<h3>\n\tSAML Certificate<\/h3>\n<p>If there is a SAML certificate, place the name of the certificate in the behavior setting named KEY_ENTRY_ID and place the certificate in the key store.&nbsp; The default certificate name is SPKey.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Security Assertion Markup Language (SAML) is an open standard that allows an identity provider (IDP) to pass authorization credentials to a service provider (SP). SAML is the link between the authentication of users&#8217; identities and the authorization to use a service from the provider.&nbsp; ExtraView relies on the use of a third party IDP. SAML&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_acf_changed":false,"_lmt_disableupdate":"","_lmt_disable":"","_kad_blocks_custom_css":"","_kad_blocks_head_custom_js":"","_kad_blocks_body_custom_js":"","_kad_blocks_footer_custom_js":"","_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"footnotes":""},"class_list":["post-22343","page","type-page","status-publish","hentry"],"acf":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v25.1 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>SAML Authentication - Product Documentation<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/docs.extraview.com\/v22\/saml-authentication\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"SAML Authentication - Product Documentation\" \/>\n<meta property=\"og:description\" content=\"Security Assertion Markup Language (SAML) is an open standard that allows an identity provider (IDP) to pass authorization credentials to a service provider (SP). SAML is the link between the authentication of users&#8217; identities and the authorization to use a service from the provider.&nbsp; ExtraView relies on the use of a third party IDP. SAML...\" \/>\n<meta property=\"og:url\" content=\"https:\/\/docs.extraview.com\/v22\/saml-authentication\/\" \/>\n<meta property=\"og:site_name\" content=\"Product Documentation\" \/>\n<meta property=\"article:modified_time\" content=\"2024-02-16T00:32:15+00:00\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"6 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/docs.extraview.com\/v22\/saml-authentication\/\",\"url\":\"https:\/\/docs.extraview.com\/v22\/saml-authentication\/\",\"name\":\"SAML Authentication - Product Documentation\",\"isPartOf\":{\"@id\":\"https:\/\/docs.extraview.com\/v22\/#website\"},\"datePublished\":\"2024-02-15T22:48:40+00:00\",\"dateModified\":\"2024-02-16T00:32:15+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/docs.extraview.com\/v22\/saml-authentication\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/docs.extraview.com\/v22\/saml-authentication\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/docs.extraview.com\/v22\/saml-authentication\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/docs.extraview.com\/v22\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"SAML Authentication\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/docs.extraview.com\/v22\/#website\",\"url\":\"https:\/\/docs.extraview.com\/v22\/\",\"name\":\"ExtraView Product Documentation\",\"description\":\"ExtraView Documentation\",\"publisher\":{\"@id\":\"https:\/\/docs.extraview.com\/v22\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/docs.extraview.com\/v22\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/docs.extraview.com\/v22\/#organization\",\"name\":\"ExtraView Corporation\",\"url\":\"https:\/\/docs.extraview.com\/v22\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/docs.extraview.com\/v22\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png\",\"contentUrl\":\"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png\",\"width\":512,\"height\":512,\"caption\":\"ExtraView Corporation\"},\"image\":{\"@id\":\"https:\/\/docs.extraview.com\/v22\/#\/schema\/logo\/image\/\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"SAML Authentication - Product Documentation","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/docs.extraview.com\/v22\/saml-authentication\/","og_locale":"en_US","og_type":"article","og_title":"SAML Authentication - Product Documentation","og_description":"Security Assertion Markup Language (SAML) is an open standard that allows an identity provider (IDP) to pass authorization credentials to a service provider (SP). SAML is the link between the authentication of users&#8217; identities and the authorization to use a service from the provider.&nbsp; ExtraView relies on the use of a third party IDP. SAML...","og_url":"https:\/\/docs.extraview.com\/v22\/saml-authentication\/","og_site_name":"Product Documentation","article_modified_time":"2024-02-16T00:32:15+00:00","twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"6 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/docs.extraview.com\/v22\/saml-authentication\/","url":"https:\/\/docs.extraview.com\/v22\/saml-authentication\/","name":"SAML Authentication - Product Documentation","isPartOf":{"@id":"https:\/\/docs.extraview.com\/v22\/#website"},"datePublished":"2024-02-15T22:48:40+00:00","dateModified":"2024-02-16T00:32:15+00:00","breadcrumb":{"@id":"https:\/\/docs.extraview.com\/v22\/saml-authentication\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/docs.extraview.com\/v22\/saml-authentication\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/docs.extraview.com\/v22\/saml-authentication\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/docs.extraview.com\/v22\/"},{"@type":"ListItem","position":2,"name":"SAML Authentication"}]},{"@type":"WebSite","@id":"https:\/\/docs.extraview.com\/v22\/#website","url":"https:\/\/docs.extraview.com\/v22\/","name":"ExtraView Product Documentation","description":"ExtraView Documentation","publisher":{"@id":"https:\/\/docs.extraview.com\/v22\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/docs.extraview.com\/v22\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/docs.extraview.com\/v22\/#organization","name":"ExtraView Corporation","url":"https:\/\/docs.extraview.com\/v22\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/docs.extraview.com\/v22\/#\/schema\/logo\/image\/","url":"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png","contentUrl":"https:\/\/docs-stg.extraview.com\/wp-content\/uploads\/2024\/03\/favicon.png","width":512,"height":512,"caption":"ExtraView Corporation"},"image":{"@id":"https:\/\/docs.extraview.com\/v22\/#\/schema\/logo\/image\/"}}]}},"taxonomy_info":[],"featured_image_src_large":false,"author_info":{"display_name":"carl.koppel","author_link":"https:\/\/docs.extraview.com\/v22\/author\/carl-koppel\/"},"comment_info":0,"_links":{"self":[{"href":"https:\/\/docs.extraview.com\/v22\/wp-json\/wp\/v2\/pages\/22343","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/docs.extraview.com\/v22\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/docs.extraview.com\/v22\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/docs.extraview.com\/v22\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/docs.extraview.com\/v22\/wp-json\/wp\/v2\/comments?post=22343"}],"version-history":[{"count":0,"href":"https:\/\/docs.extraview.com\/v22\/wp-json\/wp\/v2\/pages\/22343\/revisions"}],"wp:attachment":[{"href":"https:\/\/docs.extraview.com\/v22\/wp-json\/wp\/v2\/media?parent=22343"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}