DACS_AUTH_TRANSFER(8) | DACS Web Services Manual | DACS_AUTH_TRANSFER(8) |
NAME¶
dacs_auth_transfer - transfer credentials between federationsSYNOPSIS¶
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. 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
DACSfederation importing credentials, importation actually takes
place at a DACSjurisdiction, 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:
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.
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.
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.
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:
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:
EXPORT
•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"
•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!"
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:
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:
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
https://example.com/dacs/dacs_auth_transfer?OPERATION=EXPORT\ &TARGET_FEDERATION=DSS\ &DACS_IDENTITY=EXAMPLE:bobo
AUTH_TRANSFER_EXPORT "DSS https://dacs.dss.ca/cgi-bin/dacs/dacs_auth_transfer"
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
Transfer Clause Directives Index:
IMPORT
•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.
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:
EXIT* (Optional1)
IMPORT_ROLES "yes" ROLES* '${Auth::IMPORTED_ROLES} . ",fed1"'
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"'
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.
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.
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.
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.
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 fromFED_EX1toFED_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. 1.At J1, add a jurisdiction-specific access control rule
that allows dacs_auth_transfer to be used to export an identity:
At J2, add a jurisdiction-specific access control rule that allows
dacs_auth_transfer to be used to import an identity:
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.
<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>
<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>
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:
Note that this is the only required additional configuration at J1.
AUTH_TRANSFER_EXPORT \ "FED_EX2 https://j2.example.net/cgi-bin/dacs/dacs_auth_transfer"
3.At J2, configure dacs_auth_transfer so that it
will import credentials from FED_EX1. Add a Transfer clause to dacs.conf:
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.
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>
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:
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:
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:
https://j1.example.com/cgi-bin/dacs/dacs_auth_transfer?\ OPERATION=EXPORT&DACS_IDENTITY=FED_EX1::J1:bob
ACCEPT_ALIEN_CREDENTIALS "yes" <Transfer id="some_fed"> IMPORT_FROM "SOME_FED" REFEDERATE "YES" IMPORT_ROLES "NO" </Transfer>
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'`
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
- 2.
- ACCEPT_ALIEN_CREDENTIALS
- 3.
- dacs.acls(5)
- 4.
- dacs_auth_transfer.css
- 5.
- dacs_auth_transfer.dtd
- 6.
- AUTH_TRANSFER_EXPORT
- 7.
- SSL_PROG_CLIENT_CRT
- 9.
- AUTH_TRANSFER_TOKEN_LIFETIME_SECS
- 10.
- user()
- 11.
- AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
- 12.
- standard CGI arguments
- 13.
- dacs(1)
- 14.
- dacs(1)
- 15.
- AUTH_TRANSFER_SUCCESS_URL
- 16.
- AUTH_TRANSFER_ERROR_URL
- 19.
- dacs.conf(5)
- 21.
- www.dss.ca
- 22.
- LICENSE
07/17/2013 | DACS 1.4.28b |