blob: 9577d2982aa3e47c19d38da2ab8f29f4f78c5051 [file] [log] [blame]
type=page
status=published
title=create-auth-realm
next=create-cluster.html
prev=create-audit-module.html
~~~~~~
= create-auth-realm
[[create-auth-realm-1]][[GSRFM00015]][[create-auth-realm]]
== create-auth-realm
Adds the named authentication realm
[[sthref139]]
=== Synopsis
[source]
----
asadmin [asadmin-options] create-auth-realm [--help]
--classname realm_class [--property(name=value)[:name=value]*]
[--target target_name] auth_realm_name
----
[[sthref140]]
=== Description
The `create-auth-realm` subcommand adds the named authentication realm.
This subcommand is supported in remote mode only.
[[sthref141]]
=== Options
asadmin-options::
Options for the `asadmin` utility. For information about these
options, see the link:asadmin.html#asadmin-1m[`asadmin`(1M)] help page.
`--help`::
`-?`::
Displays the help text for the subcommand.
`--target`::
Specifies the target on which you are creating the realm. Valid values are
`server`;;
Creates the realm on the default server instance. This is the
default value.
configuration_name;;
Creates the realm in the specified configuration.
cluster_name;;
Creates the realm on all server instances in the specified cluster.
instance_name;;
Creates the realm on a specified server instance.
`--classname`::
Java class which implements this realm. These include
`com.sun.enterprise.security.auth.realm.file.FileRealm`,
`com.sun.enterprise.security.auth.realm.certificate.CertificateRealm`,
`com.sun.enterprise.security.auth.realm.jdbc.JDBCRealm`,
`com.sun.enterprise.security.auth.realm.ldap.LDAPRealm`,
`com.sun.enterprise.security.auth.realm.ldap.PamRealm`, and
`com.sun.enterprise.security.auth.realm.solaris.SolarisRealm`, or a
custom realm.
`--property`::
Optional attribute name-value pairs for configuring the authentication
realm. Authentication realms require provider-specific properties,
which vary based on implementation. +
The following properties are common to all of the supported realms,
which include `FileRealm`, `CertificateRealm`, `JDBCRealm`,
`LDAPRealm`, PamRealm, and `SolarisRealm`.
+
--
`jaas-context`;;
Specifies the Java Authentication and Authorization Service (JAAS)
context.
`assign-groups`;;
(Optional) If this property is set, its value is taken to be a
comma-separated list of group names. All clients who present valid
certificates are assigned membership to these groups for the
purposes of authorization decisions in the web and EJB containers.
--
Specific to each realm, you can specify the following properties.
* You can specify the following properties for `FileRealm`:
`file`;;
Specifies the file that stores user names, passwords, and group
names. The default is domain-dir``/config/keyfile``.
* You can specify the following properties for `CertificateRealm`:
`LoginModule`;;
Specifies the name of a JAAS `LoginModule` to use for performing
authentication. To use a JAAS `LoginModule`, you must first create
an implementation of the javax.security.auth.spi.LoginModule
interface, and then plug the module into a `jaas-context`. For more
information, see "link:security-guide/system-security.html#GSSCG00196[Custom Authentication of Client
Certificate in SSL Mutual Authentication]" in {productName} Security Guide.
* You can specify the following properties for `JDBCRealm`:
`datasource-jndi`;;
Specifies the `jndi-name` of the `jdbc-resource` for the database.
`user-table`;;
Specifies the name of the user table in the database.
`user-name-column`;;
Specifies the name of the user name column in the database's user
table.
`password-column`;;
Specifies the name of the password column in the database's user
table.
`group-table`;;
Specifies the name of the group table in the database.
`group-table`;;
Specify the group table for an authentication realm of class
`JDBCRealm`.
`group-name-column`;;
Specifies the name of the group name column in the database's group
table.
`db-user`;;
(Optional) Allows you to specify the database user name in the realm
instead of the `jdbc-connection-pool`. This prevents other
applications from looking up the database, getting a connection, and
browsing the user table. By default, the `jdbc-connection-pool`
configuration is used.
`db-password`;;
(Optional) Allows you to specify the database password in the realm
instead of the `jdbc-connection-pool`. This prevents other
applications from looking up the database, getting a connection, and
browsing the user table. By default, the `jdbc-connection-pool`
configuration is used.
`group-table`;;
Specifies the name of the group table in the database.
`digest-algorithm`;;
(Optional) Specifies the digest algorithm. The default is `SHA-256`.
You can use any algorithm supported in the JDK, or none.
+
[NOTE]
====
In versions of {productName} prior to 5.0, the default algorithm
was `MD5`. If you have applications that depend on the `MD5`
algorithm, you can override the default `SHA-25` algorithm by using
the `asadmin set` subcommand:
[source]
----
asadmin> set server.security-service.property.default-digest-algorithm=MD5
----
You can use the `asadmin get` subcommand to determine what algorithm
is currently being used:
[source]
----
asadmin> get server.security-service.property.default-digest-algorithm
----
Also note that, to maintain backward compatibility, if an upgrade is
performed from {productName} v2.x or v3.0.x to {productName}
5.0, the default algorithm is automatically set to `MD5` in cases
where the digest algorithm had not been explicitly set in the older
{productName} version.
====
+
`digestrealm-password-enc-algorithm`;;
(Optional) Specifies the algorithm for encrypting passwords stored
in the database.
+
[NOTE]
====
It is a security risk not to specify a password encryption algorithm.
====
`encoding`;;
(Optional) Specifies the encoding. Allowed values are `Hex` and
`Base64`. If digest-algorithm is specified, the default is `Hex`. If
`digest-algorithm` is not specified, by default no encoding is
specified.
`charset`;;
(Optional) Specifies the `charset` for the digest algorithm.
* You can specify the following properties for `LDAPRealm`:
`directory`;;
Specifies the LDAP URL to your server.
`base-dn`;;
Specifies the LDAP base DN for the location of user data. This base
DN can be at any level above the user data, since a tree scope
search is performed. The smaller the search tree, the better the
performance.
`search-filter`;;
(Optional) Specifies the search filter to use to find the user. The
default is `uid=%s` (`%s` expands to the subject name).
`group-base-dn`;;
(Optional) Specifies the base DN for the location of groups data. By
default, it is same as the `base-dn`, but it can be tuned, if
necessary.
`group-search-filter`;;
(Optional) Specifies the search filter to find group memberships for
the user. The default is `uniquemember=%d` (`%d` expands to the user
`elementDN`).
`group-target`;;
(Optional) Specifies the LDAP attribute name that contains group
name entries. The default is `CN`.
`search-bind-dn`;;
(Optional) Specifies an optional DN used to authenticate to the
directory for performing the search-filter lookup. Only required for
directories that do not allow anonymous search.
`search-bind-password`;;
(Optional) Specifies the LDAP password for the DN given in
`search-bind-dn`.
[[sthref142]]
=== Operands
auth_realm_name::
A short name for the realm. This name is used to refer to the realm
from, for example, `web.xml`.
[[sthref143]]
=== Examples
[[GSRFM460]][[sthref144]]
==== Example 1   Creating a New Authentication Realm
This example creates a new file realm.
[source]
----
asadmin> create-auth-realm
--classname com.sun.enterprise.security.auth.realm.file.FileRealm
--property file=${com.sun.aas.instanceRoot}/config/
admin-keyfile:jaas-context=fileRealm file
Command create-auth-realm executed successfully
----
Where `file` is the authentication realm created.
[[sthref145]]
=== Exit Status
0::
subcommand executed successfully
1::
error in executing the subcommand
[[sthref146]]
=== See Also
link:asadmin.html#asadmin-1m[`asadmin`(1M)]
link:delete-auth-realm.html#delete-auth-realm-1[`delete-auth-realm`(1)],
link:list-auth-realms.html#list-auth-realms-1[`list-auth-realms`(1)]