| 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)] |
| |
| |
