Provided by: dacs_1.4.28b-3ubuntu2_amd64 bug

NAME

       dacs_auth_transfer - transfer credentials between federations

SYNOPSIS

       dacs_auth_transfer [dacsoptions[1]]

DESCRIPTION

       This web service is part of the DACS suite.

       The dacs_auth_transfer service securely exports credentials (which represent an identity)
       from one DACS federation to another (or from DACS to a different identity management
       system), or securely imports an identity from one DACS federation to another (or from a
       different identity management system to DACS). This ability to transfer credentials (i.e.,
       import or export them) lets a DACS federation federate with another system, creating a
       "super federation" with single sign-on capability.  DACS calls such federations affiliated
       federations.

       A DACS federation can use dacs_auth_transfer to leverage authentication mechanisms not
       available to it, other systems can use it to leverage DACS, and users can potentially
       access any access-controlled resource located in any of the cooperating federations.

           In a Nutshell
           For two DACS federations, here is how the service is typically used. A user
           authenticates somewhere in Federation A, obtaining credentials understood only in that
           federation. One or more jurisdictions in Federation A will provide a link labelled
           "Transfer Login To Federation B" (or similar). Alternatively, or additionally, one or
           more jurisdictions in Federation B may provide a link labelled "Transfer Login From
           Federation A". Later, when the user decides to access resources in Federation B, he
           follows one of the links. Assuming all access control constraints are satisfied, new
           credentials will be returned to him that are understood in Federation B. His existing
           Federation A credentials continue to exist.

           The user is now recognized by both federations. If the user is known as FedA::J1:bobo
           in Federation A, then he will also be known by that name in Federation B. If
           Federation B happens to have a jurisdiction named J1 and a user at that jurisdiction
           named bobo, that user (FedB::J1:bobo) is separate and distinct as far as DACS is
           concerned.

           Note that, in general, it is not correct in the scenario above for Federation B to
           automatically initiate a credential transfer if an unauthenticated user (with respect
           to Federation B) is denied access. This is because Federation B cannot tell with which
           federation it should be initiated (if there is more than one) or even if this is
           something that the user wants done (perhaps the user needs to authenticate in the
           usual way at Federation A). Therefore, except perhaps in special circumstances,
           explicit user interaction is necessary.

       For DACS, the complete protocol is implemented by one program, dacs_auth_transfer. It
       provides the importing, exporting, and server-to-server stages of the protocol and it can
       also optionally assist middleware with the initial presentation stage of the protocol. The
       protocol is described below.

       If an identity needs to be imported to a non-DACS system, that system must implement the
       identity transfer protocol described here, or a subset of it. If a non-DACS only needs to
       export an identity to a DACS federation, it may only need a small amount of middleware to
       initiate the transfer.

           Security
            1. A small degree of cooperation is required between DACS administrators at two
               affiliated federations so that they each know how to configure the feature. The
               two federations remain autonomous, however.

            2. Transferring credentials to a DACS federation neither creates a new account nor
               creates a new identity. It merely converts credentials that were obtained in one
               federation into DACS credentials that are recognized within another federation.
               Because a DACS user identity includes a federation name, among federated DACS
               systems a user's identity is unique. After transfer to a different federation, the
               original credentials continue to exist and are unaltered.

            3. Exporting credentials to another federation and later transferring them back to
               the initial DACS federation (or exporting credentials within a federation) will
               replace the initial credentials with new ones for the same identity. The two sets
               of credentials will not be identical, however, and the imported ones may be less
               complete and therefore "weaker" than the original credentials with respect to
               authorization processing.

            4. System administrators should ensure that dacs_auth_transfer is configured so that
               it is impossible to import credentials to a federation from which they were
               exported, otherwise it may be possible for users to defeat the expiry of
               credentials by repeatedly regenerating them.

            5. The identity transfer protocol includes a server-to-server operation that must use
               SSL. The identity of the server issuing the request must be verified, either
               through its X.509 (SSL) client certificate, DACS credentials, or perhaps its IP
               address.

            6. As an additional security measure, a jurisdiction will only accept credentials for
               an identity outside of its federation if enabled by ACCEPT_ALIEN_CREDENTIALS[2].

            7. While this document talks in terms of a DACS federation importing credentials,
               importation actually takes place at a DACS jurisdiction, just as authentication
               does. That target jurisdiction is similarly responsible for the resulting
               credentials and is identified within the new credentials for access control
               testing and audit purposes.

            8. Any appropriately configured jurisdiction is capable of exporting or importing
               credentials. Some federations might choose to create "administrative
               jurisdictions" solely for this purpose (e.g., export.example.com and
               import.example.com), however, just as a federation might be structured to limit
               authentication services to a designated jurisdiction.

   The Identity Transfer Protocol
       Overview
           The ability to transfer credentials from one identity management system to another is
           a feature that can be beneficial to both users and system administrators. For users,
           it can provide the convenience of single sign-on; a user need only be authenticated by
           one federation to be able to access resources within a different federated system. For
           a system administrator, it means that fewer user identities need to be created and
           managed.

           The systems being federated might exist within a single organization or be associated
           with different, autonomous organizations that have a trust relationship, very much as
           DACS jurisdictions do. The transfer of credentials need not be reciprocal; that is,
           Federation A may allow identities to be imported from Federation B but not vice versa.

           The architecture of the transfer mechanism is primarily constrained by the typical
           browser-oriented usage of DACS, where credentials are encapsulated within an HTTP
           cookie, thereby dictating how credentials are set in an off-the-shelf browser and when
           credentials will be sent by the browser. The approach is complicated somewhat because
           a DACS user may have multiple concurrent credentials or may be unauthenticated. Also,
           a DACS federation may wish to federate with more than one foreign federation.
           Therefore, interaction with the user will sometimes be necessary so that she can
           select the particular identity to be transferred and a target federation to which that
           identity is to be transferred. A jurisdiction or federation must be able to customize
           this interaction for appropriate web site integration (i.e., look and feel), but a
           bare-bones capability must still be provided by dacs_auth_transfer.

           The design tries to balance security, usability, performance, availability,
           configuration complexity, implementation effort, administrative needs, generality, and
           extensibility, all within the constraints of the DACS architecture and requirements.

           Though it is assumed that SSL is used to secure all network communication and identify
           the communicating hosts where necessary, some major potential threats against a
           transfer capability must be addressed by the design:

            1. Replay: the system must prevent the malicious or accidental use of expired
               credentials, reuse of authentication material by a different browser user (such as
               through browser history or a bookmark), use of authentication material discovered
               in a log file, and so on

            2. Forgery and Tampering: the system must prevent a malicious user from changing
               authentication material to get different or "better" credentials using the
               transfer protocol

           Replay is addressed in the transfer protocol by restricting the exposure of
           authentication and protocol material and by limiting its validity period. Injection of
           copied material is also made difficult. Forgery and tampering are addressed through
           cryptographic means; using well-established techniques, it is thought to be
           practically impossible to create forged authentication material or modify it
           undetectably.

               Security
               Importation of identities has federation-wide ramifications but it is the
               responsibility of each jurisdiction to decide whether it will allow its
               dacs_auth_transfer service to import an identity or its rules to honour an
               identity imported by another jurisdiction within the federation. A jurisdiction
               may independently allow identities to be imported from an external system, just as
               it may unilaterally decide whether it will authenticate users and how it will do
               so. On the other hand, a jurisdiction is free to reject imported identities, just
               as it is free to reject an identity vouched for by another jurisdiction in its
               federation. Federation members may wish to establish guidelines and procedures for
               importing identities.

       Protocol Operation
           The purpose of the protocol is to transfer an identity understood by the initial
           federation to the target federation. The initial federation exports an identity; the
           target federation imports the identity.

           The four stages (operations) of the protocol are now described, in the order in which
           they are used. In all cases, "the user" can be a browser or middleware.

            1. The PRESENTATION operation, which is performed in the initial federation and is
               optional, is used for prompting the user to select the credentials to be
               transferred and identify the target federation. The purpose of the PRESENTATION
               operation is simply to make it easier for a user or middleware to invoke the
               EXPORT operation; the EXPORT operation can be invoked directly without engaging in
               this step of the protocol, however.

            2. The EXPORT operation is invoked at the initial federation by a user to request
               that the initial federation initiate the transfer of credentials representing a
               given identity to a given federation. After receiving and validating its
               arguments, the EXPORT operation invokes the TOKEN operation at the target
               federation. If the target federation tentatively approves the importation of the
               identity, it returns a URL to which the EXPORT stage redirects the user. If the
               target federation rejects the request (or the request fails), the EXPORT stage
               returns an error indication that should be reflected back to the user and
               terminates the protocol.

            3. The TOKEN operation is the heart of the protocol. By invoking it at the target
               federation, the initial federation vouches for the identity to be transferred and
               requests that the target federation honour the user's request for credentials
               valid within the target federation; the latter is free to reject the request for
               any reason. To accomplish the transfer, the initial federation requests a token
               from the target federation.

               A token is cryptographically protected, opaque information encapsulated within a
               URL as its query component; the token is meaningful only to the target federation
               (i.e., its meaning is unspecified by the protocol). It could contain a database
               key for the transaction, a nonce, or a self-contained description of the
               transaction. All that is required by the protocol is that it be kept secret among
               the communicating parties for as long as it is valid, that its validity period be
               no longer than what is required to complete the last stage of identity transfer,
               that it be difficult to forge, and that it be tamper-resistant.

               If the request for a token is granted, the target federation returns a URL that
               encapsulates it, otherwise an error indication is returned to the initial
               federation which in turn returns an error indication to the user and terminates
               the protocol.

            4. The IMPORT request is sent by the user to the target federation. A complete URL
               containing the IMPORT request will typically be created by the target federation,
               returned to the initial federation, and forwarded to the user as a browser
               redirect by the EXPORT stage. Upon successfully validating the request, which
               includes an examination of the token and checking for revocation of the identity
               (see dacs.acls(5)[3] for a description of how authentication/access revocation
               works), the target federation returns credentials (as an HTTP cookie) that are
               returned to the user in the final step of the IMPORT operation - this is the
               end-goal of the protocol - and the user is redirected by the target federation to
               an appropriate "success" URL as a convenience to the user. If the transfer fails,
               no new credentials are returned and the user is redirected to an appropriate
               "failure" URL by the target federation.

       Implementation
           The dacs_auth_transfer service implements all of the stages as separate operations of
           a single web service; a different implementation might create separate services for
           each stage or operation, or implement a subset of the functionality (e.g., it might
           only support exporting identities).

           Each of the federating systems must be assigned a unique name (for DACS, through the
           FEDERATION_NAME directive) so that identities can be globally unique.  The federating
           systems need not share a common domain name suffix.

               Note
               In the current implementation of dacs_auth_transfer, configuration information
               associated with target federations is not automatically distributed by DACS to a
               federation's jurisdictions. This means that only those jurisdictions that have
               been specifically configured to import identities will be able to do so; a
               jurisdiction will not automatically understand how to interact with a given target
               federation that is configured at a different jurisdiction. Each jurisdiction's
               administrator wanting to provide this service must configure his site's
               dacs_auth_transfer service appropriately.

           Details of the dacs_auth_transfer implementation and configuration requirements are
           now presented. A different implementation of the protocol could look very different.

           PRESENTATION
               dacs_auth_transfer can emit an HTML document to prompt the user (by default, using
               the style sheet dacs_auth_transfer.css[4]). The user selects an identity and
               target federation and submits a form. Alternatively, the information necessary to
               construct prompts can be returned within an XML document that conforms to
               dacs_auth_transfer.dtd[5]. A site is also free to implement its own presentation
               stage.

               The list of known target federation names from which a user can select is obtained
               from mappings that have been configured at this jurisdiction (see below).

               When emitting HTML, the web page generated by dacs_auth_transfer can be customized
               through the auth_transfer VFS item type. The following items are emitted if they
               exist:

               ·   header: Initial HTML to emit instead of the default.

               ·   prologue: HTML to emit immediately after the header.

               ·   instructions: HTML to emit immediately after the prologue and before the form.

               ·   form: Additional HTML to emit within the form. A likely use of this is to
                   specify a hidden TRANSFER_SUCCESS_URL argument.

               ·   epilogue: HTML to emit immediately after the form.

               ·   trailer: Final HTML to emit instead of the default.

               For example, consider the configuration directive:

                   VFS "[auth_transfer]dacs-fs:${Conf::DACS_HOME}/auth_transfer"

               If files named header and trailer exist in the directory
               ${Conf::DACS_HOME}/auth_transfer, they are expected to contain the initial and
               final HTML content, respectively. Note that these files consist of text and HTML
               markup but are not complete HTML documents.

               Customization of the HTML form is possible using configuration variables:

               ·   transfer_export_uri: the URL of the program to which the form should be
                   submitted. By default, the URL is created from the one used to invoke the
                   presentation stage, which will usually be that of dacs_auth_transfer.

               ·   transfer_submit_label: the text label to put in the form's submit button.

               ·   transfer_submit_method: the HTTP method to use to submit the form (GET is the
                   default).

               For example, the submit button's text can be specified using the directive:

                   EVAL ${Conf::transfer_submit_label} = "Execute the transfer!"

           EXPORT
               The identity to be transferred and the name of the target federation are submitted
               to dacs_auth_transfer as arguments of the EXPORT operation. The request must be
               accompanied by DACS credentials that match this identity and the target federation
               must be recognized by the receiving jurisdiction.

               For example, this URL asks the jurisdiction associated with example.com to export
               the identity EXAMPLE:bobo to the target federation DSS:

                   https://example.com/dacs/dacs_auth_transfer?OPERATION=EXPORT\
                       &TARGET_FEDERATION=DSS\
                       &DACS_IDENTITY=EXAMPLE:bobo

               For the request to succeed, credentials for EXAMPLE:bobo must be sent with the
               request, permission must be granted (by example.com) to export the identity,
               example.com must be configured with an appropriate mapping, described below, such
               that it knows how to submit a TOKEN request to a service associated with
               federation DSS, and that service must allow importation of the identity.

               The mappings of federation identifiers to URLs for export purposes are provided
               through the AUTH_TRANSFER_EXPORT[6] directive. That is, these mappings indicate
               which target federations have been configured at this jurisdiction and associate a
               target federation identifier (a short, descriptive keyword) with a URL of a web
               service that implements the TOKEN operation for the target federation. It is from
               these mappings that the list of selectable target federations is obtained.

                   Note
                   Unless jurisdictions coordinate mappings with each other, the same
                   jurisdiction must perform both the PRESENTATION and EXPORT operations.
               For example, dacs.conf might include the directive:

                   AUTH_TRANSFER_EXPORT "DSS https://dacs.dss.ca/cgi-bin/dacs/dacs_auth_transfer"

               This directive specifies one target federation, identified by the name DSS, and
               associates it with the URL of a service implementing the TOKEN operation.

                   Security
                   The TOKEN operation must be performed over a secure communication channel,
                   typically using SSL. URLs appearing in these mappings should therefore specify
                   https. The issuer of the TOKEN operation may identify itself using an SSL
                   client certificate; if SSL_PROG_CLIENT_CRT[7] is configured, that certificate
                   will automatically be used.

                   If the issuer of the TOKEN operation possesses DACS credentials obtained
                   offline from the target federation (e.g., using dacscookie(1)[8]), it can
                   specify that they be sent with the request by putting them in an object named
                   FEDNAME.cookies relative to the auth_transfer item type. directory
                   ${Conf::DACS_HOME}/auth_transfer, one cookie per line. The FEDNAME filename
                   suffix is the federation identifier for the importing federation.

                   For instance, given the AUTH_TRANSFER_EXPORT directive and the VFS directive
                   for auth_transfer above, all cookies found in a file named
                   /usr/local/dacs/auth_transfer/DSS.cookies would be sent with the TOKEN
                   operation to identify the initial federation. These cookies would have been
                   obtained from federation DSS over a secure communication channel.

           TOKEN
               The syntax and semantics of a token are meaningful only to the target federation
               and can be changed without affecting any initial federation. In the current
               implementation, the token is comprised of information such as the identity to be
               transferred, the current date at the transfer federation, the client's IP address,
               and (optionally) the client's role string, which is encrypted using the target
               federation's federation-wide key and base-64 encoded.

                   Note
                   The identity to be transferred must be a syntactically valid DACS username.
               The period during which a token is valid is determined solely by the target
               federation. Its lifetime will ordinarily be just a few seconds, after which it
               will be treated as invalid by the IMPORT stage. The
               AUTH_TRANSFER_TOKEN_LIFETIME_SECS[9] directive specifies this value for
               dacs_auth_transfer; if not given, a compile-time default is used.

               A jurisdiction within the target federation that provides identity importation
               must must configure at least one Transfer clause. The transfer directives are
               largely analogous to the authentication and roles directives. Each Transfer
               element must have an id attribute. Its value is merely a label (an alphabetic
               followed by zero or more alphanumerics, hyphens, and underscores) that allows the
               clause to be referenced. The id attribute values must be unique (case-sensitively)
               within the clause's Jurisdiction section.

                   Security
                   ·   An access control rule must be in place to ensure that this operation can
                       only be executed by a legitimate server belonging to a recognized initial
                       federation.

                   ·   The caller may not have supplied DACS credentials to identify itself and
                       therefore the user()[10] function may not be of use.

               Transfer Clause Directives Index:

                1. CREDENTIALS_LIFETIME_SECS (Optional1)

                2. ERROR_URL (Optional1)

                3. EXIT* (Optional1)

                4. IMPORT_FROM (Required)

                5. IMPORT_ROLES (Optional1)

                6. IMPORT_URL (Optional1)

                7. PREDICATE (Optional1)

                8. REFEDERATE (Optional1)

                9. ROLES* (Optional1)

               10. SUCCESS_URL (Optional1)

               IMPORT_FROM (Required)
                   This directive, which may be repeated, names an initial federation, as
                   identified by the INITIAL_FEDERATION argument, to which this clause applies.
                   It must be a syntactically valid federation name. These names are
                   case-sensitive.

               REFEDERATE (Optional1)
                   If "yes" (case insensitive), the federation and jurisdiction of the imported
                   identity (i.e., the DACS_IDENTITY argument) are changed to that of the target
                   jurisdiction. If this directive is unspecified or has another value, the
                   original identity is retained.

                   For example, if the TOKEN operation at jurisdiction ALPHA of federation FED2
                   is passed DACS_IDENTITY with a value of FED1::BETA:bobo and REFEDERATE is
                   enabled, then the imported identity will be FED2::ALPHA:bobo .

                       Security
                       This directive is useful in certain circumstances in that it can prevent a
                       particular individual from being known by multiple names, which may
                       complicate access control rules. It must be used with care, however.

                       Say Bobo is naturally known as ALPHA:bobo within federation FED2. If she
                       authenticates as FED1::BETA:bobo and uses dacs_auth_transfer to obtain
                       credentials in FED2, then by default her new credentials will be for the
                       name FED1::BETA:bobo; i.e., her DACS identity is retained.

                       Access control rules in FED2 may need to handle both names, however, which
                       can lead to problems. Some DACS administrators in FED2 may not even be
                       aware of FED1, and so access to FED1::BETA:bobo may be denied while access
                       to the same resource may be granted to FED2::ALPHA:bobo.

                       If no two distinct identities in FED1 can be mapped to the same identity
                       in FED2 (i.e., the same username component is not associated with more
                       than one jurisdiction that can export the identity to FED2), then the
                       administrator at the initial federation can advise the administrator at
                       the target federation that the REFEDERATE directive should be enabled.
                       Transferred identities will then be modified to appear to have been
                       authenticated by FED2::ALPHA. When this feature is configured, although
                       Bobo authenticates as FED1::BETA:bobo, her imported identity will be
                       FED2::ALPHA:bobo.

                       If enabling this directive would cause two or more distinct identities to
                       be mapped to the same DACS identity, the directive should not be used
                       because different individuals may be assigned the same DACS name in the
                       target federation.

               PREDICATE (Optional1)
                   The value of this directive is an expression. If the expression does not
                   evaluate to True, importation will not be permitted.

               CREDENTIALS_LIFETIME_SECS (Optional1)
                   This directive is used to override the value of the
                   AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS[11] directive or the default.

               IMPORT_ROLES (Optional1)
                   If "yes" (case insensitive), any roles in the existing credentials will be
                   copied to the new credentials. The roles must be syntactically valid at the
                   target jurisdiction. Within the context of the clause, the variable
                   ${Auth::IMPORTED_ROLES} is assigned the roles string. The default is "no".

               IMPORT_URL (Optional1)
                   This is the URL of the IMPORT stage of the protocol. By default, this is the
                   same as that of the TOKEN stage, which is correct for dacs_auth_transfer since
                   it implements all stages of the protocol.

               SUCCESS_URL (Optional1)
                   If the transfer is successful and the user has not specified another URL via
                   the TRANSFER_SUCCESS_URL argument, the user will be redirected to SUCCESS_URL.
                   This directive is used by dacs_auth_transfer in the IMPORT stage.

               ERROR_URL (Optional1)
                   If the transfer fails and the user has not specified another URL via the
                   TRANSFER_ERROR_URL argument, the user will be redirected to ERROR_URL. This
                   directive is used by dacs_auth_transfer in the IMPORT stage.

               ROLES* (Optional1)
                   The value of this directive is an expression that is evaluated at run-time.
                   Provided an error does not occur, the resulting string becomes the role string
                   for the new credentials. The new role string must be syntactically valid at
                   the target jurisdiction. The variable ${Auth::IMPORTED_ROLES} is initialized
                   to the role string (if any - see IMPORT_ROLES) from the existing credentials
                   and is assigned the value of the expression.

                   For example, to add fed1 to those found in the existing credentials:

                       IMPORT_ROLES "yes"
                       ROLES* '${Auth::IMPORTED_ROLES} . ",fed1"'

               EXIT* (Optional1)
                   The value of this directive is an expression that is evaluated at run-time.
                   Provided an error does not occur, side effects from the evaluation may alter
                   the final result of the clause. The variable ${Auth::IMPORTED_ROLES} is
                   initialized to the role string (if any - see IMPORT_ROLES) from the existing
                   credentials and ${Auth::IMPORTED_USERNAME} is assigned the (tentative)
                   imported username component from the imported credentials. Either variable may
                   be modified by the expression. The new role string must be syntactically valid
                   at the target jurisdiction. The new username must be syntactically valid.

                   This directive maps all imported usernames to guest, relative to the target
                   jurisdiction:

                       EXIT* '${Auth::IMPORTED_USERNAME} = "guest"'

           IMPORT
               An IMPORT request is validated before being accepted, which includes examining the
               token and checking for revocation of the identity. There is no guarantee that if
               the TOKEN operation succeeds the IMPORT operation will also.

               DACS credentials imported by dacs_auth_transfer are marked as being alien and
               imported, the jurisdiction that executed the importation is recorded, and the IP
               address associated with the user's initial credentials are associated with the new
               credentials; these characteristics can be tested using the dacs.exprs(5)[10]
               function.

                   Security
                   An access control rule must be in place to ensure that this operation can only
                   be executed by appropriate users. Access might well be granted to any user but
                   might reasonably be restricted based on IP address, etc.

           To recap, assuming dacs_auth_transfer is used to transfer credentials between two DACS
           federations (which we will call Federation A and Federation B) and no errors occur,
           the flow of control will typically be as follows:

            1. The user follows a link that invokes dacs_auth_transfer at some jurisdiction
               within Federation A.

            2. dacs_auth_transfer generates an HTML document that is displayed on the user's
               browser. The user selects a target federation (Federation B) and credentials to
               transfer from those presented within an HTML form and submits it, invoking
               dacs_auth_transfer at Federation A again, but this time to perform the EXPORT
               operation. The list of credentials from which the user can choose depends on the
               user's current credentials in Federation A. The list of target federations depends
               on those known to the jurisdiction that processes the request.

            3. The dacs_auth_transfer at Federation A processes the EXPORT operation and invokes
               the TOKEN operation at Federation B. This action is transparent to the user. The
               response from Federation B is a URL that represents a complete IMPORT operation
               directed at Federation B. The EXPORT operation redirects the user's browser to
               that URL.

            4. Upon receiving the redirect, the user's browser invokes the IMPORT operation at
               Federation B.  Federation B returns new credentials and redirects the user's
               browser to a configured or requested URL.

           To interoperate with dacs_auth_transfer to import DACS credentials, a program must
           implement the TOKEN operation. It must also provide functionality similar to that of
           the IMPORT operation. Because the TOKEN operation returns a URL encapsulating an
           IMPORT request to which the client is redirected, however, the IMPORT operation can be
           implementation-dependent and does need to interoperate with dacs_auth_transfer.

           To interoperate with dacs_auth_transfer to export credentials to a DACS federation, a
           program must be capable of invoking dacs_auth_transfer with the TOKEN operation and
           its arguments, and redirect the client to the URL provided by dacs_auth_transfer.

   Web Service Arguments
       In addition to the standard CGI arguments[12], dacs_auth_agent understands a variety of
       arguments that depend on the operation being requested. The descriptions of the arguments
       that follow are therefore grouped by operation.

       The additional arguments accepted by dacs_auth_transfer follow.

       Presentation
           For this stage, the value of the OPERATION argument is PRESENTATION (case
           insensitive).

           The FORMAT argument (see dacs(1)[13]) determines the type of output, with the default
           being HTML.

           Additional arguments:

           REDIRECT_DEFAULT
               If "yes" and there is exactly one set of credentials and one target federation
               (i.e., there is nothing for the client to select), then automatically redirect the
               client to a URL representing the EXPORT stage of the protocol. Though the client
               will not be required to submit a form, he will not have the opportunity to see
               which identity is being transferred or the name of the target federation.

       Export
           For this stage, the value of the OPERATION argument is EXPORT (case insensitive).

           Additional arguments:

           DACS_IDENTITY
               This is the identity corresponding to the credentials to be exported, expressed as
               a full DACS user identity (see dacs(1)[14]).

           TARGET_FEDERATION
               This is the jurisdiction's identifier for the federation to which the selected
               credentials are to be transferred. The user will typically select this identifier
               from a list produced by the same jurisdiction that performs the PRESENTATION
               operation.

           TRANSFER_SUCCESS_URL
               If the transfer operation is successful, the user will be redirected to this URL.

           TRANSFER_ERROR_URL
               If the transfer operation fails, the user will be redirected to this URL. If
               unspecified, the AUTH_TRANSFER_ERROR_URL will be used if configured, otherwise a
               message will be emitted.

           DACS_DEBUG
               If "yes", operate in a debugging mode.

       Token
           For this stage, the value of the OPERATION argument is TOKEN (case insensitive).

           Additional arguments:

           DACS_IDENTITY
               The value of this argument is identical to the argument of the same name that is
               passed to the EXPORT stage. If the transfer succeeds, this is the identity for
               which new credentials will be issued.

           INITIAL_FEDERATION
               This is the identifier for the federation that received the EXPORT request. The
               target federation must have a mapping for this identifier.

           CLIENT_ADDR
               The IP address from which the EXPORT request was issued.

           TRANSFER_SUCCESS_URL
               If the transfer operation is successful, the user wants to be redirected to this
               URL. If unspecified, a default URL will be used.

           TRANSFER_ERROR_URL
               If the transfer operation fails, the user will be redirected to this URL. If
               unspecified, a default URL will be used.

           DACS_DEBUG
               If "yes", operate in a debugging mode.

       Import
           For this stage, the value of the OPERATION argument is IMPORT (case insensitive).

           Additional arguments:

           TOKEN
               This is the value of the token returned by a previous call to the TOKEN stage of
               the protocol.

           TRANSFER_SUCCESS_URL
               If the transfer operation is successful, the user wants to be redirected to this
               URL. If unspecified, a default URL configured at the target federation using the
               AUTH_TRANSFER_SUCCESS_URL[15] directive will be used.

           TRANSFER_ERROR_URL
               If the transfer operation fails, the user wants to be redirected to this URL. If
               unspecified, a default URL configured at the target federation using the
               AUTH_TRANSFER_ERROR_URL[16] will be used.

           DACS_DEBUG
               If "yes", operate in a debugging mode.

EXAMPLE

       The following example describes step-by-step how to configure two DACS federations,
       FED_EX1 (example.com) and FED_EX2 (example.net), to enable credentials to be transferred
       from FED_EX1 to FED_EX2. For FED_EX1, the jurisdiction J1 (j1.example.com) will be
       configured to export credentials and for FED_EX2, J2 (j2.example.net) will be configured
       to import credentials. The example assumes that these two jurisdictions have already
       installed and configured DACS and that it is possible to authenticate (obtain credentials)
       somewhere within FED_EX1.

           Note
           This example will not actually work without changing the domain names, URLs, and
           identities that it uses for demonstration purposes to those configured for your
           federations and jurisdictions. Having successfully reproduced this example
           functionality on your systems, it should be apparent how to extend it for additional
           jurisdictions and federations, and how to make credential transfer bidirectional.

        1. At J1, add a jurisdiction-specific access control rule that allows dacs_auth_transfer
           to be used to export an identity:

               <acl_rule status="enabled">
                <services>
                 <service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_auth_transfer"'/>
                </services>

                <rule order="allow,deny" pass_credentials="all">
                 <allow>
                   user("auth") and (${Args::OPERATION} eq "PRESENTATION"
                     or ${Args::OPERATION} eq "EXPORT")
                 </allow>
                </rule>
               </acl_rule>

           At J2, add a jurisdiction-specific access control rule that allows dacs_auth_transfer
           to be used to import an identity:

               <acl_rule status="enabled">
                <services>
                 <service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_auth_transfer"'/>
                </services>

                <rule order="allow,deny" pass_credentials="all">
                 <allow>
                   (from("j1.example.com") and ${Args::OPERATION} eq "TOKEN")
                     or ${Args::OPERATION} eq "IMPORT"
                 </allow>
                </rule>
               </acl_rule>

               Security
               In particular, the rule at the target federation must restrict access based on the
               identity, or possibly the IP address, associated with the request. If the
               cookie-based authentication method is used, the rule would test for that specific
               identity.

        2. At J1, configure dacs_auth_transfer to know how to invoke the TOKEN operation so that
           it can export credentials to FED_EX2. Add this directive to dacs.conf:

               AUTH_TRANSFER_EXPORT \
                 "FED_EX2 https://j2.example.net/cgi-bin/dacs/dacs_auth_transfer"

           Note that this is the only required additional configuration at J1.

        3. At J2, configure dacs_auth_transfer so that it will import credentials from FED_EX1.
           Add a Transfer clause to dacs.conf:

               ACCEPT_ALIEN_CREDENTIALS "yes"

               <Transfer id="fed_ex1">
               IMPORT_FROM "FED_EX1"
               SUCCESS_URL \
                 "https://j2.example.net/cgi-bin/dacs/dacs_current_credentials"
               </Transfer>

           This configuration allows credentials to be imported from federation FED_EX1. As the
           default, after successful importation users will be redirected to a page that lists
           their identities in federation FED_EX2. In practice this might point to the site's
           home page, for example. The jurisdiction must be told to recognize credentials
           imported from FED_EX2 using the ACCEPT_ALIEN_CREDENTIALS directive.

        4. The configuration can now be tested. First, authenticate somewhere within FED_EX1
           using your browser. Let's assume that you authenticated as the identity
           FED_EX1::J1:bob so that this example can refer to a specific name. Invoke this URL
           from the browser:

               https://j1.example.com/cgi-bin/dacs/dacs_auth_transfer?OPERATION=PRESENTATION

           You should be presented with a web page that displays the identity FED_EX1::J1:bob
           (and any others that happen to be in effect) and the target federation name FED_EX2
           (and any other federations specified by a AUTH_TRANSFER_EXPORT directive). It might be
           instructive to view the source for the HTML page if you are still not clear about what
           the PRESENTATION operation does. Click on the Transfer button (if necessary, first
           selecting an identity and target federation).

           One can bypass the PRESENTATION operation by directly invoking the URL:

               https://j1.example.com/cgi-bin/dacs/dacs_auth_transfer?\
               OPERATION=EXPORT&DACS_IDENTITY=FED_EX1::J1:bob

           If the transfer is successful, your browser should now possess the original
           credentials for the identity FED_EX1::J1:bob, valid within FED_EX1, and credentials
           for the identity FED_EX1::J1:bob that are valid within FED_EX2;
           dacs_current_credentials, where your browser should be redirected to in this example,
           should display the latter. Note that though issued by different sites, the two cookies
           have the same cookie name.

       The following example illustrates how an identity might be transferred from a non-DACS
       federation (SOME_FED) to a DACS federation (again, FED_EX2 via its jurisdiction J2). We
       will assume that an appropriate access control rule has been configured at J2.

       As in the previous example, at J2, configure dacs_auth_transfer so that it will import
       credentials from SOME_FED by adding a Transfer clause to dacs.conf:

           ACCEPT_ALIEN_CREDENTIALS "yes"

           <Transfer id="some_fed">
           IMPORT_FROM  "SOME_FED"
           REFEDERATE   "YES"
           IMPORT_ROLES "NO"
           </Transfer>

       This configuration allows credentials to be imported from federation SOME_FED.

       A system administrator must write a small program, run somewhere within SOME_FED, that
       will invoke dacs_auth_transfer at J2 with appropriate arguments. The program might be run
       automatically as part of the login procedure at SOME_FED or explicitly by providing a link
       that a user can follow (e.g., labelled "Transfer Login To FED_EX2", or similar). The
       program simply invokes the TOKEN operation at J2 and, if successful, redirects the user to
       the URL that is returned to it by dacs_auth_transfer (which represents an IMPORT
       operation). If the IMPORT operation succeeds, the user will be issued an HTTP cookie
       bearing the DACS credentials. If desired, the URL that the user should visit after a
       successful transfer can be specified through the TRANSFER_SUCCESS_URL argument.

       The program might initiate the transfer by constructing and invoking a URL (via the POST
       method) much like this:

           import_url=`http -p INITIAL_FEDERATION "SOME_FED" \
             -p DACS_IDENTITY "FED_EX2::J2:bobo" \
             -p CLIENT_ADDR 127.0.0.1 \
             -p TRANSFER_SUCCESS_URL \
               "https://j2.example.net/cgi-bin/dacs/dacs_current_credentials" \
             -p OPERATION TOKEN \
             'https://j2.example.net/cgi-bin/dacs/dacs_auth_transfer'`

       Here, the requested DACS identity is FED_EX2::J2:bobo. If the response looks like a URL,
       then the TOKEN operation succeeded; to continue the transfer, the program must redirect
       the user to the URL. In this example, if credentials are returned to the user, the user
       will be redirected to dacs_current_credentials by DACS (which is useful for testing but
       unlikely in actual use).

FILES

       dacs_auth_transfer.css[4]

DIAGNOSTICS

       The program exits 0 if everything was fine, 1 if an error occurred.

SEE ALSO

       dacs_authenticate(8)[17], dacs_auth_agent(8)[18], dacs.conf(5)[19]

BUGS

       The jurisdictional meta information should be extended to identify importing and exporting
       jurisdictions (e.g., as reported by dacs_list_jurisdictions(8)[20]).

       It should be possible to optionally perform comparative checks on the IP address from
       which the EXPORT request was issued and the IP address from which the IMPORT request was
       issued. At present, if they are not identical a warning message is logged but importation
       is allowed.

       The current implementation is stateless on the server side. By including a nonce in the
       token, the possibility of replay could be further reduced.

       A mechanism for mapping imported names may be needed.

       Although the credential's DACS role string is passed to the target federation, a flexible
       mechanism for optionally including them in the imported credentials should be added.

       The protocol should be improved with respect to peer identification for the TOKEN
       operation.

AUTHOR

       Distributed Systems Software (www.dss.ca[21])

COPYING

       Copyright2003-2012 Distributed Systems Software. See the LICENSE[22] file that accompanies
       the distribution for licensing information.

NOTES

        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. ACCEPT_ALIEN_CREDENTIALS
           http://dacs.dss.ca/man/dacs.conf.5.html#ACCEPT_ALIEN_CREDENTIALS

        3. dacs.acls(5)
           http://dacs.dss.ca/man/dacs.acls.5.html

        4. dacs_auth_transfer.css
           http://dacs.dss.ca/man//css/dacs_auth_transfer.css

        5. dacs_auth_transfer.dtd
           http://dacs.dss.ca/man/../dtd-xsd/dacs_auth_transfer.dtd

        6. AUTH_TRANSFER_EXPORT
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_TRANSFER_EXPORT

        7. SSL_PROG_CLIENT_CRT
           http://dacs.dss.ca/man/dacs.conf.5.html#SSL_PROG_CLIENT_CRT

        8. dacscookie(1)
           http://dacs.dss.ca/man/dacscookie.1.html

        9. AUTH_TRANSFER_TOKEN_LIFETIME_SECS
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_TRANSFER_TOKEN_LIFETIME_SECS

       10. user()
           http://dacs.dss.ca/man/dacs.exprs.5.html#user

       11. AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS

       12. standard CGI arguments
           http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args

       13. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html

       14. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#naming

       15. AUTH_TRANSFER_SUCCESS_URL
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_TRANSFER_SUCCESS_URL

       16. AUTH_TRANSFER_ERROR_URL
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_TRANSFER_ERROR_URL

       17. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

       18. dacs_auth_agent(8)
           http://dacs.dss.ca/man/dacs_auth_agent.8.html

       19. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

       20. dacs_list_jurisdictions(8)
           http://dacs.dss.ca/man/dacs_list_jurisdictions.8.html

       21. www.dss.ca
           http://www.dss.ca

       22. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE