Use Secure Credentials

When an operation requires authentication to an external system, instead of directly supplying credentials, you can use a secure credential.

To use a secure credential, specify its name in your server-side code. MarkLogic Server then applies the credential according to its defined rules.

Secure credentials are used with built-in functions that support external authentication, such as HTTP requests and directory lookups. The credential determines how authentication is performed and whether the request is permitted, based on the target resource and the roles of the calling user.

With an HTTP request

HTTP requests require a secure credential with a target URI pattern configured with target authentication of basic or digest.

If you know the name of the secure credential that you want to use, then you can retrieve the id and use it as part of your transaction. The following example uses a credential named localAdmin:

xquery version "1.0-ml";

let $url := "http://localhost:8001"
let $credential-id := xdmp:credential-id("localAdmin")
let $options :=<options xmlns="xdmp:http">
       <credential-id>{$credential-id}</credential-id>
     </options>
return xdmp:http-get($url, $options)

Alternatively, MarkLogic Server can discover the applicable credentials using the target URL. MarkLogic Server compares the target URL to the target URI pattern configured in the secure credential:

xquery version "1.0-ml";

declare namespace sec = "http://marklogic.com/xdmp/security";

let $url := "http://localhost:8001"
let $credential := xdmp:credentials($url)[last()]
let $credential-id := $credential/sec:credential-id/data()
let $options :=<options xmlns="xdmp:http">
       <credential-id>{$credential-id}</credential-id>
     </options>
return xdmp:http-get($url, $options)

Because xdmp:credentials() may return multiple credentials matching the target URL, use [1] or [last()] to avoid passing a sequence to the function.

With an LDAP request

LDAP requests require a secure credential with a target URI pattern configured with target authentication of md5 (deprecated in MarkLogic 11.3.2), simple or external.

If you know the name of the secure credential that you want to use, then you can retrieve the id and use it as part of your transaction. The following example uses a credential named ldapUser:

xquery version "1.0-ml";

let $credential-id := xdmp:credential-id("ldapUser")
return xdmp:ldap-search(
  "(cn=TestUser 1)",
  <options xmlns="xdmp:ldap">
    <credential-id>{$credential-id}</credential-id>
    <bind-method>simple</bind-method>
    <server-uri>ldap://dc1.mltest1.local:389</server-uri>
    <search-base>CN=Users,DC=MLTEST1,DC=LOCAL</search-base>
  </options>
)

Alternatively, MarkLogic Server can discover the applicable credentials using the target server URI. MarkLogic Server compares the server URI to the target URI pattern configured in the secure credential:

xquery version "1.0-ml";

declare namespace sec = "http://marklogic.com/xdmp/security";

let $server-uri := "ldap://dc1.mltest1.local:389"
let $credential := xdmp:credentials($server-uri)[last()]
let $credential-id := $credential/sec:credential-id/data()
return xdmp:ldap-search(
  "(cn=TestUser 1)",
  <options xmlns="xdmp:ldap">
    <credential-id>{$credential-id}</credential-id>
    <bind-method>simple</bind-method>
    <server-uri>{$server-uri}</server-uri>
    <search-base>CN=Users,DC=MLTEST1,DC=LOCAL</search-base>
  </options>
)

Because xdmp:credentials() may return multiple credentials matching the target URL, use [1] or [last()] to avoid passing a sequence to the function.